Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / oasis.zip / OASDOC1.TXT < prev next >

Wrap

Text File | 1988-08-05 | 521KB | 16,435 lines

Open Architecture Open Architecture Screen Interface System Screen Interface System ( O A S I S ) ( O A S I S ) Version 4.1 - Evaluation Version 4.1 - Evaluation EUREKA SOFTWARE ASSOCIATES EUREKA SOFTWARE ASSOCIATES REFERENCE MANUAL REFERENCE MANUAL OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual O A S I S NOTICE NOTICE ______ This document and the information contained herein as well as the described software 'OASIS' (Open Architecture Screen Interface System) are protected by international copyright law and treaty provisions. They are provided to you under a shareware scheme whose conditions and terms are explained in Appendix B of this manual and may only be used in accordance with these conditions. Both this documentation and the program are provided strictly on an Both this documentation and the program are provided strictly on an 'As Is' Basis. 'As Is' Basis. There is no warranty, expressed or implied, with respect to the program or the documentation, including but not limited to merchantability and fitness for a particular purpose with respect to defects in the program or the documentation. In no event shall Martin Hossfeld be liable for any loss of profit or any other damage, including but not limited to special, incidental, consequential or other damages. Copyright (C) 1987, 1988 EUREKA SOFTWARE ASSOCIATES Martin Hossfeld Remy Fesnoux 12, Pinewood Green 2344 Yorkshire Iver Heath, Bucks. SL0 0QP Ann Arbor, MI 48104 United Kingdom USA All Rights Reserved. All Rights Reserved. OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Acknowledgements Acknowledgements ________________ IBM, IBM PC, XT, AT and PC DOS are trademarks of International Business Machines Corporation. Burroughs and TD830 are trademarks of Unisys Corporation. Turbo Pascal is a registered trademark of Borland International Inc. MS DOS is a registered trademark of Microsoft Corporation. Hercules Craphics Card is a trademark of Hercules Computer Technology. OASIS, SFD, SCL, Screen Format Designer, Screen Control Language and Open Architecture Screen Interface System are trademarks of EUREKA SOFTWARE ASSOCIATES. 'Lightning' is a trademark of PCSG Inc. OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Introduction Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 12 What is OASIS? . . . . . . . . . . . . . . . . . . . . . . 12 About this manual . . . . . . . . . . . . . . . . . . . . . 13 What this manual assumes . . . . . . . . . . . . . . . . . 14 What you will learn . . . . . . . . . . . . . . . . . . . . 14 Chapter I Chapter I . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 The Screen Format Designer (SFD) . . . . . . . . . . . . . 20 The Screen Control Language (SCL) . . . . . . . . . . . . . 21 Application programs written with OASIS . . . . . . . . . . 22 Some Feature Explanations . . . . . . . . . . . . . . . . . 23 Screen Related Program Parameters . . . . . . . . . . 23 Colors and Display Attributes . . . . . . . . . . . . 23 Non Standard Keyboard Layouts . . . . . . . . . . . . 23 Program development with OASIS . . . . . . . . . . . . . . . . . 24 A. Declarative Phase . . . . . . . . . . . . . . . . . . . 24 B. Procedural Phase . . . . . . . . . . . . . . . . . . . . 25 Differences to traditional program development . . . . . . . . . 26 What instead of how . . . . . . . . . . . . . . . . . . . . 26 Early Tests . . . . . . . . . . . . . . . . . . . . . . . . 26 Less Programming . . . . . . . . . . . . . . . . . . . . . 26 Easier changes . . . . . . . . . . . . . . . . . . . . . . 26 Nationalization, customization made simple . . . . . . . . 26 System Installation and Setup . . . . . . . . . . . . . . . . . 27 The Distribution Disks . . . . . . . . . . . . . . . . . . 27 System Requirements . . . . . . . . . . . . . . . . . . . . 28 Installation Instructions . . . . . . . . . . . . . . . . . 29 Chapter II Chapter II . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Explanation of keyboard functions . . . . . . . . . . . . . . . 33 Variables and Constants . . . . . . . . . . . . . . . . . . 33 Variable field specials . . . . . . . . . . . . . . . . . . 34 Editing keys . . . . . . . . . . . . . . . . . . . . . . . 34 Return . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Escape . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Function keys . . . . . . . . . . . . . . . . . . . . . . . 36 Errors & Automatic Help System . . . . . . . . . . . . . . . . . 37 Invalid data entry . . . . . . . . . . . . . . . . . . . . 37 Missing mandatory data . . . . . . . . . . . . . . . . . . 37 Autohelp feature . . . . . . . . . . . . . . . . . . . . . 37 Design Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Designing a format layout . . . . . . . . . . . . . . . . . 40 Layout editor - Meaning of keys . . . . . . . . . . 41 Changing the Format Size . . . . . . . . . . . . . . . 42 Introduction page 4 Introduction page 4 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Drawing fields . . . . . . . . . . . . . . . . . . . . 43 Drawing boxes . . . . . . . . . . . . . . . . . . . . 44 Selecting Linestyles . . . . . . . . . . . . . . . . . 45 Field specifications . . . . . . . . . . . . . . . . . 46 Format Control Specifications . . . . . . . . . . . . 49 User Function Key Specifications . . . . . . . . . . . 49 Testing a Format . . . . . . . . . . . . . . . . . . . . . 51 Change field specs/Active field . . . . . . . . . . . 51 Change field specs/Other field . . . . . . . . . . . . 51 Global Colors/Attributes . . . . . . . . . . . . . . . 51 Format/Control Specs . . . . . . . . . . . . . . . . . 51 Colors/Attributes . . . . . . . . . . . . . . . . . . . . . 52 Field Attributes . . . . . . . . . . . . . . . . . . . 52 Color Screen Attributes . . . . . . . . . . . . . . . 53 Monochrome Attributes . . . . . . . . . . . . . . . . 54 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . 55 Functional Description - Introduction . . . . . . . . . . . . . 57 SFD Basic Program Layout . . . . . . . . . . . . . . . . . 58 Files used by SFD . . . . . . . . . . . . . . . . . . . . . 59 SFD.FOR . . . . . . . . . . . . . . . . . . . . . . . 59 SFD.FIN . . . . . . . . . . . . . . . . . . . . . . . 59 SFD.MSG . . . . . . . . . . . . . . . . . . . . . . . 59 SFD.ERR . . . . . . . . . . . . . . . . . . . . . . . 59 SFD.DEF . . . . . . . . . . . . . . . . . . . . . . . 59 Files generated by SFD . . . . . . . . . . . . . . . . . . 60 <workfile>.SCS . . . . . . . . . . . . . . . . . . . . 60 <workfile>.SCI . . . . . . . . . . . . . . . . . . . . 60 <workfile>.MSG . . . . . . . . . . . . . . . . . . . . 60 Basic Keyboard Functions . . . . . . . . . . . . . . . . . 61 Online Help Facility . . . . . . . . . . . . . . . . . . . 62 Explanatory field input informations . . . . . . . . . 62 AutoHelp . . . . . . . . . . . . . . . . . . . . . . . 62 Format Help . . . . . . . . . . . . . . . . . . . . . 62 Field Help . . . . . . . . . . . . . . . . . . . . . . 62 Input Error Handling . . . . . . . . . . . . . . . . . . . 63 Invalid Key . . . . . . . . . . . . . . . . . . . . . 63 Wrong data . . . . . . . . . . . . . . . . . . . . . . 63 Missing mandatory data . . . . . . . . . . . . . . . . 63 The Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . 64 The Menu Header . . . . . . . . . . . . . . . . . . . . . . 64 Act DIR . . . . . . . . . . . . . . . . . . . . . . . 64 Workfile . . . . . . . . . . . . . . . . . . . . . . . 64 Formats . . . . . . . . . . . . . . . . . . . . . . . 64 The Main body . . . . . . . . . . . . . . . . . . . . . . . 64 The Message Line . . . . . . . . . . . . . . . . . . . . . 64 DESIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Load File . . . . . . . . . . . . . . . . . . . . . . . . . 66 CHDir . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Crunch . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Introduction page 5 Introduction page 5 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Undelete . . . . . . . . . . . . . . . . . . . . . . . . . 68 Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 68 DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Formats . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Directory . . . . . . . . . . . . . . . . . . . . . . . . . 69 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Single format . . . . . . . . . . . . . . . . . . . . . . . 70 All formats . . . . . . . . . . . . . . . . . . . . . . . . 70 Format list . . . . . . . . . . . . . . . . . . . . . . . . 70 DEFAULTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Design . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Left Field Limit . . . . . . . . . . . . . . . . . . . 71 Right Field Limit . . . . . . . . . . . . . . . . . . 71 Background Color . . . . . . . . . . . . . . . . . . . 71 Foreground Color . . . . . . . . . . . . . . . . . . . 71 Surrounding Area . . . . . . . . . . . . . . . . . . . 72 System defaults . . . . . . . . . . . . . . . . . . . . . . 73 Auto Help . . . . . . . . . . . . . . . . . . . . . . 73 After n Errors . . . . . . . . . . . . . . . . . . . . 73 Beep yes/no . . . . . . . . . . . . . . . . . . . . . 73 Length (ms) . . . . . . . . . . . . . . . . . . . . . 73 Pitch (Hz) . . . . . . . . . . . . . . . . . . . . . . 73 Field Blink Frequency . . . . . . . . . . . . . . . . 73 Char YES . . . . . . . . . . . . . . . . . . . . . . . 74 Char NO . . . . . . . . . . . . . . . . . . . . . . . 74 Cursor Wraparound Disabled . . . . . . . . . . . . . . 74 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Terminate Program . . . . . . . . . . . . . . . . . . . . . 75 Format Design . . . . . . . . . . . . . . . . . . . . . . . . . 76 Basic Work Flow . . . . . . . . . . . . . . . . . . . . . . . . 76 The Layout Editor . . . . . . . . . . . . . . . . . . . . . 77 Layout editor Meaning of keys . . . . . . . . . . . . 78 Drawing Fields . . . . . . . . . . . . . . . . . . . . 79 Special Functions . . . . . . . . . . . . . . . . . . 80 Menu Functions . . . . . . . . . . . . . . . . . . . . 83 Format Specifications . . . . . . . . . . . . . . . . 85 The Test Feature . . . . . . . . . . . . . . . . . . . . . 94 Introduction . . . . . . . . . . . . . . . . . . . . . 94 The local Menu . . . . . . . . . . . . . . . . . . . . 94 System Limitations . . . . . . . . . . . . . . . . . . 95 Chapter III Chapter III . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 100 SCL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Introduction page 6 Introduction page 6 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL.TPU . . . . . . . . . . . . . . . . . . . . . . . . . . 101 SCL.ERR . . . . . . . . . . . . . . . . . . . . . . . . . . 101 SCL - Global Declarations . . . . . . . . . . . . . . . . . . . 102 General . . . . . . . . . . . . . . . . . . . . . . . . . . 102 SCL Control Parameters . . . . . . . . . . . . . . . . . . 103 Max_Error_Messages . . . . . . . . . . . . . . . . . . 103 Max_Input_Messages . . . . . . . . . . . . . . . . . . 103 Max_Heap_Screens . . . . . . . . . . . . . . . . . . . 103 File Names . . . . . . . . . . . . . . . . . . . . . . . . 104 Screenfile_Ext . . . . . . . . . . . . . . . . . . . . 104 Indexfile_Ext . . . . . . . . . . . . . . . . . . . . 104 Errorfile_Ext . . . . . . . . . . . . . . . . . . . . 104 Messagefile_Ext . . . . . . . . . . . . . . . . . . . 104 Help System Parameters . . . . . . . . . . . . . . . . . . 105 Autohelp_Screen . . . . . . . . . . . . . . . . . . . 105 Maxerrors . . . . . . . . . . . . . . . . . . . . . . 105 Auto_Help_Set . . . . . . . . . . . . . . . . . . . . 105 Code_Help_Field . . . . . . . . . . . . . . . . . . . 105 Code_Help_Format . . . . . . . . . . . . . . . . . . . 105 Beep Parameters . . . . . . . . . . . . . . . . . . . . . . 106 Beep_Off . . . . . . . . . . . . . . . . . . . . . . . 106 Beep_Time . . . . . . . . . . . . . . . . . . . . . . 106 Beep_Frequency_1 . . . . . . . . . . . . . . . . . . . 106 Beep_Frequency_2 . . . . . . . . . . . . . . . . . . . 106 Message Display . . . . . . . . . . . . . . . . . . . . . . 107 Input_Msg_Set . . . . . . . . . . . . . . . . . . . . 107 Error_Msg_Set . . . . . . . . . . . . . . . . . . . . 107 Field Attributes . . . . . . . . . . . . . . . . . . . . . 108 Blink_Count . . . . . . . . . . . . . . . . . . . . . 108 Timer_Intervall . . . . . . . . . . . . . . . . . . . 108 Mark_Field_Left . . . . . . . . . . . . . . . . . . . 108 Mark_Field_Right . . . . . . . . . . . . . . . . . . . 108 Key Specifications . . . . . . . . . . . . . . . . . . . . 109 Code_Cancel_Act . . . . . . . . . . . . . . . . . . . 109 Code_Abort . . . . . . . . . . . . . . . . . . . . . . 109 Code_Escape . . . . . . . . . . . . . . . . . . . . . 109 Performing 'Edit' functions . . . . . . . . . . . . . . . . 110 Function Keys . . . . . . . . . . . . . . . . . . . . . . . 110 Nationalisation Parameters . . . . . . . . . . . . . . . . 111 Code_Yes . . . . . . . . . . . . . . . . . . . . . . . 111 Code_No . . . . . . . . . . . . . . . . . . . . . . . 111 Character sets for Variables . . . . . . . . . . . . . . . 111 Country Information Parameters . . . . . . . . . . . . . . 112 SCL_Country . . . . . . . . . . . . . . . . . . . . . 112 Country . . . . . . . . . . . . . . . . . . . . . . . 112 Date_Format . . . . . . . . . . . . . . . . . . . . . 112 Date_Separator . . . . . . . . . . . . . . . . . . . . 112 Time_Separator . . . . . . . . . . . . . . . . . . . . 113 Currency . . . . . . . . . . . . . . . . . . . . . . . 113 SCL Control Parameters . . . . . . . . . . . . . . . . . . 114 Introduction page 7 Introduction page 7 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Progpath . . . . . . . . . . . . . . . . . . . . . . . 114 No_Wrap . . . . . . . . . . . . . . . . . . . . . . . 114 Format Pointers . . . . . . . . . . . . . . . . . . . . . . 115 S_Ptr . . . . . . . . . . . . . . . . . . . . . . . . 115 R_Ptr . . . . . . . . . . . . . . . . . . . . . . . . 115 W_Ptr . . . . . . . . . . . . . . . . . . . . . . . . 116 Format Handling Parameters . . . . . . . . . . . . . . . . 117 Active_Field . . . . . . . . . . . . . . . . . . . . . 117 Char_Code . . . . . . . . . . . . . . . . . . . . . . 117 Glb_Error . . . . . . . . . . . . . . . . . . . . . . 117 Format Handling Parameters . . . . . . . . . . . . . . . . 118 User_Function . . . . . . . . . . . . . . . . . . . . 118 Begin_Of_Field . . . . . . . . . . . . . . . . . . . . 118 End_Of_Field . . . . . . . . . . . . . . . . . . . . . 118 End_Of_Format . . . . . . . . . . . . . . . . . . . . 119 Checkrequired . . . . . . . . . . . . . . . . . . . . 119 Screen related Parameters . . . . . . . . . . . . . . . . . 120 Screen_Mode . . . . . . . . . . . . . . . . . . . . . 120 Mono_Adapter . . . . . . . . . . . . . . . . . . . . . 120 Color_True . . . . . . . . . . . . . . . . . . . . . . 120 Format related Parameters . . . . . . . . . . . . . . . . . 121 Xoff . . . . . . . . . . . . . . . . . . . . . . . . . 121 Yoff . . . . . . . . . . . . . . . . . . . . . . . . . 121 Background Processing Parameters . . . . . . . . . . . . . 122 LP_Background_Pointer . . . . . . . . . . . . . . . . 122 HP_Background_Pointer . . . . . . . . . . . . . . . . 122 Miscellaneous Parameters . . . . . . . . . . . . . . . . . 123 Glb_Status . . . . . . . . . . . . . . . . . . . . . . 123 Glb_Ok . . . . . . . . . . . . . . . . . . . . . . . . 123 Format_Aborted . . . . . . . . . . . . . . . . . . . . 123 Global Type Declarations . . . . . . . . . . . . . . . . . 124 Procedures and Functions . . . . . . . . . . . . . . . . . . . . 125 Introduction . . . . . . . . . . . . . . . . . . . . . . . 125 Entering and leaving SCL . . . . . . . . . . . . . . . . . 126 Structure of a SCL Program . . . . . . . . . . . . . . . . 127 Loading and displaying formats . . . . . . . . . . . . . . 128 X_Max and Y_Max . . . . . . . . . . . . . . . . . . . . . . 130 Handling format input . . . . . . . . . . . . . . . . . . . 131 Format Handling Control . . . . . . . . . . . . . . . . . . 133 Reading/Writting Format Fields . . . . . . . . . . . . . . 134 Introduction . . . . . . . . . . . . . . . . . . . . . 134 Reading Field Content . . . . . . . . . . . . . . . . 135 Writing Field Content . . . . . . . . . . . . . . . . 137 Deleting Field Content . . . . . . . . . . . . . . . . 138 Reading the 'Selected' Attribute . . . . . . . . . . . 139 Writing the 'Selected' Attribute . . . . . . . . . . . 140 String Handling routines . . . . . . . . . . . . . . . . . 141 System Functions . . . . . . . . . . . . . . . . . . . . . 145 Date related routines . . . . . . . . . . . . . . . . . . . 147 Time related Routines . . . . . . . . . . . . . . . . . . . 149 Introduction page 8 Introduction page 8 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Background Processing Tasks . . . . . . . . . . . . . . . . 150 Other Routines . . . . . . . . . . . . . . . . . . . . . . 151 Chapter IV Chapter IV . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Data Communications Subsystem . . . . . . . . . . . . . . . . . 155 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Global Communications Parameters . . . . . . . . . . . . . 157 Timers and Delays . . . . . . . . . . . . . . . . . . . . . 158 Data Communications Control Characters . . . . . . . . . . 159 Other Declarations . . . . . . . . . . . . . . . . . . . . 160 Procedures and Functions . . . . . . . . . . . . . . . . . . . . 162 Initializing and Terminating DC . . . . . . . . . . . . . . 163 Sending Data . . . . . . . . . . . . . . . . . . . . . . . 164 Receiving Data . . . . . . . . . . . . . . . . . . . . . . 166 Other Functions . . . . . . . . . . . . . . . . . . . . . . 167 Low Level Routines . . . . . . . . . . . . . . . . . . . . 168 Example Programs . . . . . . . . . . . . . . . . . . . . . . . . 170 A Simple Line Monitor (SAMPLE7.PAS) . . . . . . . . . . . . 171 Listing of SAMPLE7.PAS . . . . . . . . . . . . . . . . 172 Description of SAMPLE7.PAS . . . . . . . . . . . . . . 177 A Terminal Emulator Program (SAMPLE 8) . . . . . . . . . . 179 Listing of Example Program 8 . . . . . . . . . . . . . 180 Description of SAMPLE8.PAS . . . . . . . . . . . . . . 187 Program Discussion . . . . . . . . . . . . . . . . . . . . . . . 190 Introduction . . . . . . . . . . . . . . . . . . . . . . . 191 Example 1 (OASIS Easy Fields) . . . . . . . . . . . . . . 192 Explanations of SAMPLE1.PAS . . . . . . . . . . . . . 193 Example 2 (OASIS Print Labels) . . . . . . . . . . . . . . 195 Explanations of SAMPLE2.PAS . . . . . . . . . . . . . 196 Example 3 (OASIS Formats Stack) . . . . . . . . . . . . 200 Listing of SAMPLE3.PAS . . . . . . . . . . . . . . . . 201 Explanations of SAMPLE3.PAS . . . . . . . . . . . . . 202 Example 4 (OASIS Automatic Disk Menu) . . . . . . . . . . 204 Example 5 (OASIS SCL Demo) . . . . . . . . . . . . . . . . 208 Menu . . . . . . . . . . . . . . . . . . . . . . . . . 208 Country Demo . . . . . . . . . . . . . . . . . . . . . 209 Date Demo . . . . . . . . . . . . . . . . . . . . . . 211 Special Fields Demo . . . . . . . . . . . . . . . . . 213 SCL System Details . . . . . . . . . . . . . . . . . . . . . . . 216 Service Routines . . . . . . . . . . . . . . . . . . . . . 217 Background Processing Tasks . . . . . . . . . . . . . . . . 219 READING AND WRITING FIELDS . . . . . . . . . . . . . . . . 222 SCL Input Character Processing . . . . . . . . . . . . . . 224 The Error Message File . . . . . . . . . . . . . . . . . . 225 SCL - System Resource Considerations . . . . . . . . . . . 226 Disk Access . . . . . . . . . . . . . . . . . . . . . 226 Processor Requirements . . . . . . . . . . . . . . . . 226 Format File -Disk Space Requirements . . . . . . . . . 226 Introduction page 9 Introduction page 9 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Code Space Requirements . . . . . . . . . . . . . 226 SCL Data Space Requirements . . . . . . . . . . . . . 226 Total Memory Requirements . . . . . . . . . . . . . . 227 Tips & Tricks . . . . . . . . . . . . . . . . . . . . . . . . . 228 Entry of Characters not normally accessible via the Keyboard . . . . . . . . . . . . . . . . . . . . . . . 228 Blinking Fields . . . . . . . . . . . . . . . . . . . . . . 228 Use of the 'Intensity' field attribute on Color systems . . 228 The 'Selected' Attribute in Menus . . . . . . . . . . . . . 228 Preventing automatic termination of a format . . . . . . . 229 Highlighting text on screen formats . . . . . . . . . . . . 229 Special Fields . . . . . . . . . . . . . . . . . . . . . . 229 Storing strings in <Name>.ERR . . . . . . . . . . . . . . . 229 Using Field Input Messages for Help Screens . . . . . . . . 230 Using 'Goto_Field' . . . . . . . . . . . . . . . . . . . . 231 Alphabethic List of all User accessible SCL Procedures & Functions . . . . . . . . . . . . . . . . . . . . . . . . . 234 Datacom Control Characters . . . . . . . . . . . . . . . . . . . 237 Field Attributes and Colors . . . . . . . . . . . . . . . . . . 238 Possible Field Attributes . . . . . . . . . . . . . . . . . 238 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Functions in SCL Programs . . . . . . . . . . . . . . . . . . . 239 Standard SCL Error Messages . . . . . . . . . . . . . . . . . . 240 The Shareware Idea . . . . . . . . . . . . . . . . . . . . 241 OASIS Products & Licencing Terms . . . . . . . . . . . . . . . . 242 OASIS Demo package . . . . . . . . . . . . . . . . . . . . 242 OASIS Evaluation . . . . . . . . . . . . . . . . . . . . . 243 OASIS . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Invoice & Order Form . . . . . . . . . . . . . . . . . . . . . . 247 Order Form . . . . . . . . . . . . . . . . . . . . . . . . 247 Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Introduction page 10 Introduction page 10 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Introduction page 11 Introduction page 11 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Introduction Introduction ____________ What is OASIS? What is OASIS? OASIS stands for Open Architecture Screen Interface System. OASIS is a fourth generation programming tool to develop screen based application programs and User Interfaces on Micro Computers. No one can deny that computers still primarily rely on visual and tactile means of communication to interact with its users. With the proliferation of microcomputers in recent years, as more and more people became users they consequently behaved as consumers who implicitly stressed the emphasis on human interfacing, as a result products offered more and more ergonomic features. Among the top features speed is definitely high on the list. Obviously the first and most tangible advantage of fast applications is an overall gain of time to complete a given project, however this is certainly not the most important one. What matters more is the response time, in other words the time it takes for the application to process elementary tasks which if not carefully timed induce unnecessary and undesirable delays. Neglecting this factor, no matter how small or hardly perceptible delays can be, invariably results in operator's irritations that may in some cases lead to reject the product. Otherwise what the user wants is in essence a tool easy to use, quick to learn with sufficient help information readily available on line, flexible but logical and powerful, in other word something comfortable and easy on the eyes that meet his expectations. On the other side of the fence we have the programer who is tasked to satisfy all these requirements while focussing on performance thus making the product attractive and marketable within a tight schedule in order to be one of the first in this competitive marketplace. This is precisely where OASIS come into play to serve the interests of all parties. OASIS is an immensely powerful tool for the programmer because it allows him to cut down development time while ensuring outstanding human interface features and still focus on the intrinsic part of the application thus optimizing its resources and performances. How OASIS achieves this is described in the product overview. To illustrate what has just been is said here you ought to know that OASIS and more specifically SFD (Screen File Designer) itself has been designed using the semantics that governs SCL (Screen Control Language) itself and for that reason is indeed an application of itself, in other words SFD was designed using SFD, a sort of CATCH 22 scenario. To sum up this brief introduction one could say that OASIS is to the DESIGN AND MANAGEMENT OF USER INTERFACE what the advent of wordprocessors in the mid 1970's has done to TEXT WRITING AND EDITING. Introduction page 12 Introduction page 12 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual About this manual About this manual _________________ This manual describes OASIS and its various components and how to use them. This book articulates itself around three chapters followed by one appendix. CHAPTER I System Overview CHAPTER I System Overview The purpose of this chapter is to arouse the interest of the reader by describing OASIS main components and listing their features. CHAPTER II Screen File Designer (SFD) CHAPTER II Screen File Designer (SFD) After a short introduction to SFD you will be paced through a comprehensive tutorial followed by a chapter providing a functional description of SFD. CHAPTER III Screen Control Language (SCL) CHAPTER III Screen Control Language (SCL) This chapter discusses in details the major procedures and functions that constitute the heart of the system. CHAPTER IV SCL Data Communication subsystem CHAPTER IV SCL Data Communication subsystem Since OASIS can be used in a micro to mainframe environment this chapter is entirely dedicated to the DataCommunication extensions of SCL. APPENDIX A APPENDIX A This chapter covers several advanced OASIS features and also contains descriptions and discussions of 5 sample programs. APPENDIX B APPENDIX B Lists and Tables. OASIS products & Licencing Terms. Introduction page 13 Introduction page 13 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual What this manual assumes What this manual assumes ________________________ In order to fully exploit the Secret of SCL the reader is expected to have some experience with programming languages and especially TURBO PASCAL. We assume that the reader can refer to BORLAND manuals and references in order to write SCL programs, compile, debug and run them. What you will learn What you will learn ___________________ The best method to learn something new is to practice, make mistakes and learn from them. From the very beginning, you will have at the tip of your fingers all the power and the flexibility of the Screen Format Designer SFD, you will soon realize how intuitive it can be and it won't take long before you become familiarized with all the keyboard functions and the system features. The tutorial in chapter II will pace you step by step in the design of a trivial screen letting you exercise almost every function of SFD. Within a couple of hours you will be able to design and test fully fledged screens. Chapter III provides you with the basic architecture to elaborate complex programs including multiple stacked screens (windows) and background processing tasks. Chapter IV will let you include data communication routines to deal with the outside world. Finally a set of programming tips is available in Appendix A to the expert to fine tune complex applications to a breathtaking level. We hope that you will very shortly be able to unleash the full power of OASIS to your benefit, your limits being your own imagination. Good luck and have a good time. Introduction page 14 Introduction page 14 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual This Page is intentionally left blank Introduction page 15 Introduction page 15 Chapter I Chapter I OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Open Architecture Open Architecture Screen Interface System Screen Interface System ( OASIS ) ( OASIS ) System Overview and Features System Overview and Features Chapter I, System Overview and Features page 17 Chapter I, System Overview and Features page 17 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Overview Overview ________ OASIS allows you to create and handle state-of-the-art screen OASIS interfaces with many outstanding features in a most comfortable and efficient way. Due to its background processing capabilities the handling of datacom and so on can also be easily achieved. OASIS is OASIS not an application generator. Typically, application generators require some kind of a macro language which is usually rather limited in terms of flexibility. This often results in slow running, clumsy applications a too high price to be paid for added programming convenience. Instead, OASIS is built on top of Turbo Pascal, leaving all features OASIS of this powerful development system available to you for special requirements OASIS may not be capable to fulfill. OASIS With OASIS you can OASIS * Add Micro based front ends to existing mainframe programs, taking over anything from Screen Management up to local data storage etc. * Build the Micro part of distributed processing applications. * Write completely Micro based Applications utilizing virtually any number of screen formats. * Develop sophisticated Terminal Emulators. OASIS is a sophisticated and powerful user interface design and OASIS management system that both simplifies the task of the application writer and provides a very attractive interface to the end user. Using OASIS not only results in tremendeous time savings (depending OASIS on the kind of application between 50 and 90 percent) but also achieves perfect results. Chapter I, System Overview and Features page 18 Chapter I, System Overview and Features page 18 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual OASIS has two main components: OASIS has two main components: The Screen Format Designer (SFD) The Screen Format Designer (SFD) The Screen Control Language (SCL) The Screen Control Language (SCL) Screen Format Designer (SFD) Screen Format Designer (SFD) SFD is an integrated application program, itself written with OASIS, SFD OASIS introducing a new concept in the elaboration of screen formats. It allows the user to interactively design any screen format layouts on the principle of what you paint is what you get. Away from the host application SFD lets you define all field parameters of the format plus a large suite of other refinements such as related error messages and help screens. Futhermore SFD enable you to dynamically ___________ test new formats before you even wrote a single line of code. ____ Screen Control Language (SCL) Screen Control Language (SCL) SCL is a extensive collection of Turbo Pascal Source Routines built SCL to cater for all aspects of format access, display, window management, data capture, input check, display of error messages, help system. By simply including these routines in any Turbo Pascal Program, all of its features can be used just like a very high level, straightforward and easy to learn language extension to Turbo Pascal. This not only leaves all flexibility to the programmer, but enables him to create highly professional applications with many outstanding features in a fraction of the time usually required, which contributes to reducing development costs considerably. Chapter I, System Overview and Features page 19 Chapter I, System Overview and Features page 19 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Screen Format Designer (SFD) The Screen Format Designer (SFD) ________________________________ The purpose of this program is to assist you to design, specify and test all screen formats to be incorporated in an application program. These formats are 'built' in a straightforward but comprehensive approach using a full screen editor for the format layout and a series of pop-up menus to define field and global parameters. Finally under each single format name are stored not only the form description layout and its field definitions but any information related to that format such as reference to help screens. Key features of SFD include : Key features of SFD include : - Easy to understand, Menu Driven Program with Windows. - Online accessible, context sensitive Help facility. - Layout design with comfortable Full Screen editor. - Full characterset access. - Drawing of Boxes with the opportunity to choose any linestyles and automatic interconnections to other boxes. - Powerful Block Copy and Delete functions. - Outstanding selection of display attributes and highlightfunctions, seperate for color and monochrome displays. - A large range of pre-defined fieldtypes. - Input validation selectable for any field. - Up to 50 fields per format. - Option to define and link 'Help' formats and assistance messages to any single field. - Unrestricted formats size up to 80 x 25. - Number of formats per program only limited by disk space. - Transfer of formats between different format files. - Printing of format lists and hard copies. - Complete inbuilt test facility for new formats. - Dynamic alteration of format specs. and attributes during test with results immediately being visible. - Full support of MSDOS 2+ Subdirectory structure. Chapter I, System Overview and Features page 20 Chapter I, System Overview and Features page 20 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Screen Control Language (SCL) The Screen Control Language (SCL) _________________________________ SCL is an extensive set of routines to access SFD generated format SCL SFD files and to perform all screen related functions within a Turbo Pascal program. The main features of SCL are: The main features of SCL are: - Powerful command syntax (Processing of a complete format including input check and error handling with only three statements). - Automatic control of display and overlay of formats. - Easy and comfortable access to fields. - Support of windows including stacking to any desired depth, only limited by the amount of memory available. - Handling of menus, even multiple menus and/or together with data input fields on one format. - Full control of display attributes and formatting of fields. - Automatic input validity checks and display of error messages. - No requirement to declare field variables etc. in your program. - User programmed checks or other interferences possible anytime made simple and safe. - Capability to monitor and flag user selectable keyboard keys and other events. - Changes to Formats, Messages and Input check parameters are possible without recompiling the program. - Highly improved conciseness and ease of understanding of finished programs. - Comprehensive library of procedures and functions to facilitate date/time processing, access to DOS functions, string handling, (data communication with full reease) and much more. - Support of execution of other programs and even DOS commands from within an application. - Support of background processing tasks (datacom, printing etc). Chapter I, System Overview and Features page 21 Chapter I, System Overview and Features page 21 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Application programs written with OASIS. Application programs written with OASIS. ________________________________________ The use of OASIS results in very ergonomic application programs with The use of OASIS outstanding handling capabilities and many userfriendly features like: - Automatic display of assisting messages for each single field. - Extensive Online Help System with four different, user selectable levels. - Automatic Input error handling and display of error messages. - Adaptability to different systems/keyboard layouts. - Simple and straightforward Nationalisation and Customisation. - Full Support for both Color and Monochrome displays. - Undo function. - Abort function. - Mouse support very simple to accomplish. - Interrupt driven Data Communications Handling Chapter I, System Overview and Features page 22 Chapter I, System Overview and Features page 22 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Some Feature Explanations. Some Feature Explanations. __________________________ Screen Related Program Parameters Screen Related Program Parameters In OASIS written application programs most screen related parameters OASIS are stored in data files. This includes the format layouts themselves, the field details, error messages, help and explanatory information, field input check/validation parameters, colors, attributes and much more. All these parameters can be altered anytime using SFD. SFD This presents several advantages: 1. Program changes are often possible without recompiling. 2. Nationalisation and customisation of programs, otherwise often very tedious and time consuming tasks become effortless and easy to accomplish. 3. The program sources are more compact, easier to understand and do compile faster. Colors and Display Attributes Colors and Display Attributes OASIS written applications automatically recognize the type of OASIS display adapter and therefore utilize the suitable screen attributes. For optimum result, two totally independent sets of attributes are provided for each format/field, one for color graphic and one for monochrome display adapters. Note: OASIS works in 80 column modes only. Note: Non Standard Keyboard Layouts Non Standard Keyboard Layouts SCL written applications can easily be adapted to non standard SCL Keyboards. The Codes of all relevant keys are stored as constants and can be adapted as required. Chapter I, System Overview and Features page 23 Chapter I, System Overview and Features page 23 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Program development with OASIS Program development with OASIS ______________________________ It is made up of two distinct phases. A. Declarative Phase A. Declarative Phase This Phase is completely performed using SFD. It consists of the SFD following steps: 1. Define all screen formats and fields required. For each Format do the following: 2. Using the screen editor, design its layout including location and size of all required fields. 3. Using pop-up menus then specify the appearance of the format, define whether special checks are required or not for this format and establish if and when other external actions are to be performed. 4. Always using pop-up menus determine if and in which fields error and explanatory messages are to be displayed. 5. Again using pop-up menus specify for each field, the type (Variable, Constant, Output) and define its parameters like special appearance, attributes, formatting, necessary checks, explanatory message,inter field dependencies and so on. 6. Finally test the format using the SFD test facilities. The SFD format behaves just as if it was already integrated in your program. You can therefore safely test input checks, formatting, help system and many other things. You may find that you are not satisfied with one or another detail. No problem, you can do most changes right away, without even leaving the test. The results will be immediately visible to you. Only for some major changes like basic layout or field types you would have to go back to the Design facility. 7. Once you are pleased with your format, you can assign help screens to it (this can be done anytime later on). There are many different possibilities for the help system, please look under "The OASIS Help System" for details. "The OASIS Help System" Chapter I, System Overview and Features page 24 Chapter I, System Overview and Features page 24 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual B. Procedural Phase B. Procedural Phase 1. Now the time has come to actually begin programming using SCL SCL constructs. The first approach is to build some sort of skeleton program, containing all switching logic between different formats and so forth. 2. You then compile this skeleton and experiment with the basic logic to assess its functionality and see if it is what you wanted initially. By now, you will have an exact idea how the final program will look like and you already have spared yourself precious time since you will require a lot less testing and changes later on. 3. You complete your program by adding all the missing logic into the skeleton. 4. You perform the final testing and fine tuning as required. Chapter I, System Overview and Features page 25 Chapter I, System Overview and Features page 25 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Differences to traditional program development Differences to traditional program development ______________________________________________ What instead of how What instead of how Obviously the first difference with conventional user interface approach is that you do not have to specify how your formats are to be built. As a matter of fact this is the essence of the OASIS concept. All you have to do is draw them and tell SFD what they should look like. It is no longer neccessary to write procedures to check or to format the fields content. As a general rule, just declare what should be done, not how to do ____ ___ it. Early Tests Early Tests Most of the necessary test work can be performed at quite an early stage of the program development, ensuring that conceptual errors are detected early enough to take corrective actions before things get out of control. Less Programming Less Programming Another strength resides in the fact that much of the programming is already done before you even start to generate a program source. Once you really start programming, you will realize that SCL constructs SCL allow you to remain in the declarative mode. Since you don't have to declarative develop procedures, you can concentrate on more global aspects of your program and, as a side effect, you'll save a considerable amount of time. Easier changes Easier changes During program development a lot of changes have to be made to the program. Even once a program is finished, you usually never really stop changing it. For programs written with OASIS this becomes a lot OASIS easier. If the changes are in the screen interface, you can usually perform them via SFD without even recompiling the program. Even if SFD this is not the case, it becomes a lot easier to do since your program source is much more concise and thus more intelligible. Nationalization, customization made simple Nationalization, customization made simple All screen formats and all program messages are stored in data files, easily accessible with SFD. Customisation of screens and/or messages SFD or even translation of a whole program into other languages become mondaine tasks, without even recompiling the program. Chapter I, System Overview and Features page 26 Chapter I, System Overview and Features page 26 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual System Installation and Setup System Installation and Setup _____________________________ The Distribution Disks The Distribution Disks On the OASIS Distribution disks you'll find the following files: On the OASIS Distribution disks you'll find the following files: READ.ME Textfile containing last minute information. SCL.TPU Turbo Pascal 4.0 Unit file containing all Screen Screen Control Language (SCL) Routines and definitions. Control Language In order to access SCL you must include 'SCL' in your 'USES' statement. SCL.DOC Source of the 'Interface' Part of SCL.TPU. SFD.EXE Screen Format Designer Program. SFD.ERR Text file containing error messages for SFD.EXE. SFD.MSG Data file containing explanatory program messages for SFD.EXE. SFD.FOR Screenfile for SFD.EXE. SFD.FIN Screen index file. SCL.ERR Optional (Error-) Message file to be used for your programs. You can add your own messages as required. SAMPLExS Turbo Pascal program examples to demonstrate SCL. SAMPLEx.EXE Compiled versions of the above. SAMPLEx.SCS Screenfiles to above. SAMPLEx.SCI Indexfiles to above. SAMPLEx.MSG Message files to above. SAMPLEx.ERR Error messages to above. Chapter I, System Overview and Features page 27 Chapter I, System Overview and Features page 27 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual System Requirements System Requirements IBM PC or compatible 256 KB Memory minimum Hard disk *) PC DOS/MS-DOS 2.0 or later Turbo Pascal 4.0 or later *) Note: Note The Screen Format Designer program requires a hard disk in order to Screen Format Designer run. Other typical Application Programs build with OASIS normally run OASIS happily on a floppy system. See Appendix A for Details on System Resource Considerations. See Appendix A for Details on System Resource Considerations. Chapter I, System Overview and Features page 28 Chapter I, System Overview and Features page 28 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Installation Instructions Installation Instructions _________________________ There is no special Installation procedure necessary since OASIS is not copy protected. Just create a subdirectory on your hard disk and copy the content of both distribution disks to it. Now add to your CONFIG.SYS file the following two statements: FILES=16 FILES=16 BUFFERS=32 BUFFERS=32 If your configuration file should already contain a "FILES=nn" statement, then you just increase the number to at least 16; if it is already bigger, leave it as it is. The same applies to the "BUFFER=nn" Statement. This completes the installation. To start the Screen Design Program just go to the subdirectory you've loaded the distribution disks to (using the DOS Command "CD") and enter SFD<Return>. SFD Chapter I, System Overview and Features page 29 Chapter I, System Overview and Features page 29 Chapter II Chapter II OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Chapter II, SFD getting started page 31 Chapter II, SFD getting started page 31 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Screen Format Designer The Screen Format Designer ( S F D ) ( S F D ) Getting Started Getting Started (A Short Tutorial) (A Short Tutorial) Chapter II, SFD getting started page 32 Chapter II, SFD getting started page 32 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Explanation of keyboard functions Explanation of keyboard functions At first you will probably find the following explanations rather complicated and confusing, but upon trying you will soon find that everything does function in a very intuitive way and you will very quickly get familiar with it. Much care has been taken regarding the way the different functions are layed out to achieve ease of operation and a maximum of ergonomy. Variables and Constants Variables and Constants Variables and Constants are the two main categories of format fields. Whenever you happen to see the cusor, either as a blinking underline character or as a big block (which may or may not blink) you are in a Variable field and you are expected to enter some data. Variable If the cursor is not visible you are in a Constant field. You can't Constant enter any data into Constants, all you can do is to select or deselect them by pressing Return or Enter. A typical example for Return Enter. Constant fields is a Menu. You just select one (in some cases more Constant than one) possibility out of a choice being presented to you. The keys to travel between fields and their functions are as follows: The keys to travel between fields and their functions are as follows: Right : Next Field. Left : Previous Field. Down : First field on next line. Up : Last field on previous line. Home : First field in line. End : Last field in line. PgDn : Last field on format. PgUp : First field on format. Tab : Next field.*) ShiftTab : Previous field.*) Note: Note: *) Tab and Right respectively ShiftTab and Left are not identical. See next paragraph. Chapter II, SFD getting started page 33 Chapter II, SFD getting started page 33 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Variable field specials Variable field specials Upon approaching a Variable field you will realize several things happening. 1. The present content of the field (if there is any) is being shifted to the left, no matter how it was formatted before. this is done in order to facilitate the entry or change of data. 2. In some cases, the part of the field not yet containing data is flushed with Fill characters (usually dots) or the whole field Fill is being underlined. Whichever the case, the intention is to give you an indication of the length of the field, i.e. how much space is left for data input. 3. The Cursor is visible in form of a blinking Underline character. Once you start entering data, the shape of the cursor changes to a big block which may or may not blink. This indicates that you are now in Entry mode and that the left and right arrows have changed their Entry meaning. Now Right advances you one character position and Left moves Right Left you to the previous character. Note that Tab and ShiftTab keep their Tab ShiftTab original functions. If you press Right while already being in the Right rightmost position of the field or if you press Left while being at Left the first character of the field you will be notified by a Beep. Beep. Besides just entering data, there is an alternate method to change from Travel to Entry mode : Pressing Return. This is especially handy Travel Entry Return in cases where you want to change already existing data in a field and you need to advance to the appropriate character position(s) using the arrows. arrows Editing keys Editing keys Backspace : Deletes character left of cursor. Insert : Inserts a space at cursor position. Delete : Deletes character under cursor. Note: Entering data into the rightmost position of a Variable Note: Variable automatically advances you to the next field. Chapter II, SFD getting started page 34 Chapter II, SFD getting started page 34 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Return Return As previously mentioned, pressing Return while in a Variable field Return Variable puts you into Entry Mode. Once you are in Entry mode pressing Return Entry Entry Return finishes this field an advances you to to the next one or, if this field was the last one, terminates the format. The resulting effect on the field content varies depending on your position within the field. If you were in the first position, the entire current field content is captured. For all other positions only the portion of the field left of the cursor is recognized. While in a Constant field, pressing Return toggles the status of the Constant Return field from not selected to selected and vice versa. The cursor will not selected selected automatically be advanced to the next field. In case you are already in the last field the format will be terminatedn In some cases, Constant fields can form a group, typically some kind Constant of a menu. In these cases only one field out of that group may be selected at any given time. So, if you select a field other than the one presently already selected, the latter one will automatically be deselected. If a field of such a group has been selected, the cursor automatically advances to the field immediately following the group (in case there is none left, the format will be automatically terminated). Selecting an item out of a group of Constant fields may or may not be Constant mandatory. In case it is, you are not allowed to deselect a field deselect (i.e. pressing Return in a field being presently selected results in Return selected a Beep or an error message to be displayed). Beep In such cases, deselecting a field is automatically done as soon as deselecting you select another field. This is very much the same as on a TV-Set select where you deselect a channel by just choosing another one. Escape Escape Escape can be used to tell the program independently of the cursor position that you are finished with the present format and you want to exit it. Chapter II, SFD getting started page 35 Chapter II, SFD getting started page 35 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Function keys Function keys F1 F1 Pressing F1 displays General Help Informations including key F1 functions etc. F2 F2 F2 displays specific Informations relative to what you are presently doing. Please note that F2 help is not available for every format. In F2 help such cases, if you press F2 you will just hear a beep. F2 beep. F3 F3 The UNDO key. Pressing F3 will restore the content of your present F3 field to whatever it was before you changed it; i.e. will UNDO your changes. Note that UNDO only applies to Variable fields. Variable F10 F10 The ABORT key. Pressing F10 tells the program that you want to F10 unconditionally abort your present operation. Any data you may have entered on your present format will be lost. For this reason, Abort Abort is only available with a few formats. Formats where Abort is not available can typically only be exited by Abort hitting the Escape key while the data fields are empty. Escape Other (local) functions Other (local) functions On some formats there may be further functions available. Pressing F1 F1 (Help) will always give you the appropriate details. Chapter II, SFD getting started page 36 Chapter II, SFD getting started page 36 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Errors & Automatic Help System Errors & Automatic Help System ______________________________ Invalid data entry Invalid data entry Whenever you try to enter invalid data you will be notified by a Beep Beep and, in some cases, a system generated error message may be displayedn Missing mandatory data Missing mandatory data If you attempt to exit a format before having entered all mandatory fields, the program will notify you in the same way as in the case of invalid data. In addition, the cursor will automatically be positioned into the field where data is missing. Autohelp feature Autohelp feature If you make a certain number of consecutive input errors (Default = 3) the program will automatically come up with information where and how to obtain help. Note: You can change nearly all Help system Parameters according to Note: your requirements. See under 'System Defaults' for details. Chapter II, SFD getting started page 37 Chapter II, SFD getting started page 37 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Design Cycle Design Cycle ____________ To make you familiar with the operation of SFD we will now go together through the complete cycle of design and specification of a format. During this exercise we will also look at some of the features the program offers. Once we are done with the design of your format we will test it using SFD's own test facility. Those already familiar with the basic operation of SFD can skip this Those already familiar with the basic operation of SFD can skip this part of the manual. part of the manual. Start the program by entering SFD<Return> (Make sure to be in the SFD right directory). After a short moment you will be presented with the programs main menu. It is divided into three parts. The header shows the program name, version etc as well as some informations about the directory you have selected, the workfile and the number of formats in it. Since you have just started up the program the following information should be displayed. Act dir : <The currently active drive and directory>. Workfile : <None>. Nr of Formats: 0. The middle part of the menu is occupied by a number of menu items, subdivided into seven groups. Presently, the first item (Layout) of the first group (Design) should be highlighted. The last line of the menu is called Message Line and gives you a Message Line brief explanation of the highlighted item. If you press F1 (just do it !) a screen informing you about the F1 meaning of keys etc will appear. To leave the Help format press either Return or Escape. Return Escape. F2 will give you a bit more detailed Information about the presently F2 highlighted group of items on the menu. Again, to leave the help format you must press Return or Escape. Return Escape. You can use F1 on any format, F2 may not be available in some cases. F1 F2 Chapter II, SFD getting started page 38 Chapter II, SFD getting started page 38 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual You can travel around on the menu using the appropriate keys. If you don't know which ones either look in this manual under 'Meaning of keys' or press F5. While you are traveling around on the menu, watch F5 the message line changing. | You may also want to press F2 while being in different fields and read the appropriate explanations. Once you are familiar with how to travel on a format, we can proceed to some 'real' work. | Before we start I want to remind you of the two 'Help' keys F1 and F2 During this exercise it is probably a good idea to use them very frequently (Especially F2) and read the information they containn | Don't forget that the help provided by F2 is context sensitive (i.e. the kind of information provided may change depending where you presently are on the format. Should you require further detailed informations, then read the appropriate chapter later on in this manual. Chapter II, SFD getting started page 39 Chapter II, SFD getting started page 39 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Designing a format layout Designing a format layout _________________________ 1. Travel to the appropriate item (Layout). 2. | Hit Return. This selects the item. Since you have not yet loaded a work filel SFD will come up with a SFD tiny window asking you for a name. Enter a name (without extension since SFD uses its own extensions), SFD | say 'Myfile', and press Return. The window disappears again and a new one will come up informing you that SFD will ask you whether you want to create a new format. You SFD say yes. Now you will be presented with the layout editor's worksheet (a fancy name for an empty screen, isn't it ?). It's size defaults to 25 lines with 80 characters each (a full screen). In order to familiarize you with the different features, you should | now read both the F1 and F2 help formats. | You probably have already noticed some additional functions on F4 to | F9 During our little exercise we will try out most of them. However we should first talk about the other keys. Some have a slightly different meaning as on a normal format. Chapter II, SFD getting started page 40 Chapter II, SFD getting started page 40 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Layout editor - Meaning of keys Layout editor - Meaning of keys | Backspace, Insert and Delete have the same meaning as under normal operation. | Home moves the cursor to the upper left corner of your worksheet. | End moves the cursor to the first position on the last line. | PgUp deletes the line under the cursor. | PgDn inserts a line. | Return moves the cursor to the first character of the next line. | The Arrow keys allow you to move freely on the format. Note that the | Arrows are working in wrap-around mode. This means that: | If you press Right while being in the rightmost position you will be moved to the first position of the next line. | If you press Left while being in the first position of a line you will be moved to the last position of the previous line. Right while being in the lower right corner moves you to the upper | left corner; the opposite happens if you then press Left. | Pressing Up while being in the first line moves you to the last line | and the opposite happens with Down while in the last line. Before starting to draw a format we will learn how to specify its size. (The size can actually be changed anytime during the layout design). Chapter II, SFD getting started page 41 Chapter II, SFD getting started page 41 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Changing the Format Size Changing the Format Size | Press F9. This will display the editors local menu. Select the first item (Change format size). A new window comes up with the present settings. Just enter new values, let's assume 15 lines with 40 characters each. That's it. You'll now see that the unused portion of the screen is filled with tiny dots. This is done to give you an idea of your drawing area. You will also realize that cursor movement is now confined to this area. Now we will start drawing a screen format. Chapter II, SFD getting started page 42 Chapter II, SFD getting started page 42 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Drawing fields Drawing fields In our exercise we will build a format for a rather trivial program to print address labels. While drawing it make sure that you don't put any text into the first character position on any line because we will need this space later on. First go to the second line and give the format a header of your own | choice. Once you have written it go to column 1 and press Insert until it is approximately in the center. (If you have moved it too | far, use Delete) Now go to line 4 and enter the following: [Mr][Mrs][Miss] The open square bracket means 'Begin of field', the closed means 'End of field'. In your example, the first character position of the first field is the 'M', the last is the 'r'. the field has a length of two characters. Now complete your format according to the drawing below. Move everything that it looks nice. The exact length and position of the fields does not matter at the moment, just check that you have left line 1, line 3, the line below 'City' and line 15 (the last) as well as the first and last column empty. We will need them in a moment... -Header- [Mr][Mrs][Miss] Name.......[ ] Street.....[ ] City.......[ ] Number of Labels[ ] Msg[ ] Chapter II, SFD getting started page 43 Chapter II, SFD getting started page 43 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Drawing boxes Drawing boxes Presently our format doesn't look too appealing, does it ? We will correct this now by drawing boxes around the different parts. First we want to draw a frame around the complete format. We need to | Mark two diagonal corners of the box we want to draw. Therefore we go | to line 1, Column 1 (Home) and press F5 (Mark). The mark is shown as | a small rhombus. (By the way, an accidentally set Mark can easily be | removed by positioning the cursor over it and pressing F5 again). | To get to the other (lower right) corner we can now press Left twice. | Again F5 to mark it. | Now press F8 (Draw Box). Observe !. Observe ! | Incidently, key F7 does exactly the opposite of F8, i.e you can | undraw (delete) a box with it. The box drawing feature can also be used to draw vertical or horizontal lines. Just place the two marks in either the same line or the same column. Apart from double lines as you have already seen, boxes can be drawn in all kind of line styles which ca be seperately defined for horizontal and vertical lines. To do this, go by the following instructions. Chapter II, SFD getting started page 44 Chapter II, SFD getting started page 44 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Selecting Linestyles Selecting Linestyles We now want to seperate the different parts of the format. However we would rather like to use single lines instead of double lines. In order to achieve this you go to the local menu (F9) again and select the second option (Box Linestyles) by highlighting it and pressing | Return. The small triangles you see on the format being presented to you specify the currently selected linestyles (Double lines). Since we want single lines for horizontal, highlight the second field and | press Return. The vertical lines we leave as they are. Once back on | your worksheet, go to Line 3, first column. Place a Mark. | Go to the last position of the line below 'City'. Mark it as well. (Actually you could also have marked the other two diagonal corners, i.e. line 3, last column and the first column of the line below 'City'). | Press F8 to draw the box. As you can see, all necessary Junctions are done automatically. (For your information: This applies not only for 'T', but also for (For your information: This applies not only for 'T', but also for 'X' junctions, whenever you use single or double lines). 'X' junctions, whenever you use single or double lines). By now, you should be reasonably satisfied with your format (don't be too fancy after all, it is not that terribly sophisticated anyway) and we will proceed to specify its parameters. | To leave the editor, press Escape. SFD will verify whether you really want to leave the editor, select SFD 'Yes'. Note: The program is now checking your format. If for some reason Note: you did not properly use the brackets (Field delimiters) a window will be displayed informing you of the kind of error you made. In | this case, hit Escape or Return to go back to the editor and correct your piece of art before attempting to leave it again as described above. Chapter II, SFD getting started page 45 Chapter II, SFD getting started page 45 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Field specifications Field specifications Now you should see your format (the field delimiters have been removed) and a small menu offering four different choices. We want to specify the fields of your format, so take the first one. The menu vanishes and you are back in your address label format. It now behaves like any other format you've seen so far. The first field is highlighted and you can travel around using the familiar keys. Before going further we should think a moment about your format and what it should look like. The first three fields (Mr,Mrs and Miss) should be a group of options. There is no data to be entered into these fields , we just want the user to select one (and only one) of the given options. Such | fields are called Constants in SFD. To make the selection exclusive SFD (only one may be selected) we must declare them as a group. And we also want the selection to be mandatory. To conclude. 1. We want fields 1 to 3 to be a group of selectable items (Constants). 2. We want to declare them as mandatory. Now let's do it. Go to the first field (the 'Mr') and select it by pressing Return. A window will come up giving you several options to preset the field specifications. At present, your field is set to the default values, meaning it is assumed to be a variable, any input is allowed, there are no checks to be made and some more. We don't want to preset it to anything else (all other fields are currently declared in the same way), so we choose 'None'. But we do want to change some of the specification details, so choose 'Yes'. Chapter II, SFD getting started page 46 Chapter II, SFD getting started page 46 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Now the Field specification format comes up. The 'Type' still says | Variable. We want to change it to Constant. Since the cursor is | already in the 'Type' field just press Return. A small menu will come | up. Choose 'Constant' and press Return again. That's it. The next two fields show 'Group from 1 to 1'. Change the second '1' | to '3' and press Return. | Now you go to 'Mandatory' and hit Return to change it to 'Yes'. Note: If you want to know the meaning of the other specifications, Note: | just make use of your mighty F2 Help key. At this point in time we could also specify the colors and attributes, but for the time being we will leave them unaltered at their default values and come back to them later on in this exercise. | You can now press Escape to finish the format. Since we have specified that field 1 is the first of a group ranging from field 1 to field 3, SFD automatically copies it's specifications SFD to the remaining fields of the group. There are however some specifications which are not copied: The 'message', the delimiters | and whether the field is Selected or not. The next three fields (4 to 6) on your address label format are to be | used to enter data, in other words, they are Variables. We want to make input to them mandatory. Call up the field specifications for the first one (Field Nr 4, the 'Name' field). Go to the 'Fill' field. Enter a 'dot'. Into the 'Delimiter left' field put a colon. (The colon will be displayed at the Position were you put your open square bracket when you designed the layout). Set 'Mandatory' to 'Yes'. Now leave the format. The next two fields on your format (street and city) should look the same as the 'name' field. Consequently you can use the 'Preset' function to copy the previous fields specs. As mentioned earlier, the 'Delimiters' are not copied, so, if you want to have a colon in front of these fields as well, you must specify it (otherwise you can choose the 'Details No' Option). Chapter II, SFD getting started page 47 Chapter II, SFD getting started page 47 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual There are two fields left on your format, 'Nr of Copies' and 'Msg'. 'Nr of copies': Here again you can copy the specs from the previous field. But go into the details as well since we want to specify some input check parameters. First of all, we only want Integer numbers (there is nothing like 2.4 labels). Hence go to the 'Inp.Check' field and press Return. Now make your choice. We also want to limit the Number of address labels one can obtain. We will assume a minimum of 1 and a maximum of 25 labels. Enter the appropriate values and finish the format. The 'Msg' field we want to use for error messages (If we don't | specify a field for them we would just hear a Beep in case of erroneous data input). | Specify the type as Output only and also set 'Justify' to 'Center' (just to make the messages look nice). Leave the format. | Since we now have specified all fields in your format, press Escape. You are now back in the 'Change Format Specs' menu. Chapter II, SFD getting started page 48 Chapter II, SFD getting started page 48 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Control Specifications Format Control Specifications Select 'Format Control Specs'. | Once the format is diplayed you probably best press F2 first and read the infomations to get an idea. Now let's begin. The first field we want to change is 'Error Message Field'. Enter the number of your 'Msg' field, 8. Actually, we are already finished with our specifications, but let's | take the opportunity to talk about the User Function Key specifications on the lower half of this format. User Function Key Specifications User Function Key Specifications The purpose of these specifications is to tell SCL later on in your SCL program when to invoke special user written routines like additional checks, prefilling of fields and many other things. By default, i.e. without the need to be specified, facilities are provided by SCL to SCL optionally invoke user written routines whenever a format field is entered, left or if the format is exited. In addition to this, SCL can be instructed to allow user written SCL routines to take over control whenever certain keys are pressed. In order to allow this to happen, the appropriate keys must be specified | as User Functions. SFD lets you specify any of the ten function keys and, in addition, SFD | up to ten other keys to serve as User Functions. ('Key' in this context can be any valid CNTRL or ALT key combination as well). In addition to the here mentioned Interrupt specifications which are valid throughout the whole format there is one more which can be specified for each single field. You may have seen it already when you did the field specifications. It is called 'CharCheck' and, if set, can invoke a user written procedure at each single keystroke if the cursor is in the appropriate field. As you probably can imagine, the possibilities offered by the User Interrupt System are enormous. Advice and examples on how to use them are provided in A[[endix A. Further informations can also be found in the SCL part of this SCL manual. Chapter II, SFD getting started page 49 Chapter II, SFD getting started page 49 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual We have now completed the format specification (colors and attributes | will be discussed during the format test). Press Escape to go back to the little 'Specifications' Menu and select 'End'. Your format is now written to the format file on disk and you are back in the Main Program Menu. If you look at 'Nr of formats' in the header of the menu, you'll see '1', indicating that you have created your first format. If you want, you can print a hardcopy of it on your printer before we continue to test it and try out the Color/Attribute specifications. By now you should have a better understanding of some of SFD's SFD's features and I hope that you have enjoyed our exercise so far. When you are ready to continue, we will take a look at SFD's Format SFD Test feature. Chapter II, SFD getting started page 50 Chapter II, SFD getting started page 50 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Testing a Format Testing a Format ________________ | Select Design Test/Modify on the main menu. When asked for the name of the format you want to test, enter 'Myformat' or whatever name you called it. If you entered the wrong name, you will be notified by a | Beep. In this case, either correct it or, if you don't know the name | anymore, press F10 to get back to the main menu and use the Display | Formats option to find out the right one. Anyway, as soon as you have entered the name of your format, press | Return and it will be displayed. It now behaves exactly according to your specifications. All input checks are being performed and if you enter something wrong or forget to enter mandatory data you will be notified. Take yourself a couple of minutes to try out all kind of things like leave off mandatory data, try to enter invalid data etc and watch the results. Note: Handling of a format under 'Test' is a lot slower than later Note: on in the program. This limitation is imposed by the fact that all messages must be read from a disk file as opposed to later on in the program where they are stored in memory. Now let us modify the way it looks. | To do this, you have to select the local menu (you know how, don't you ?). This menu offers the following choices: Change field specs/Active field Change field specs/Active field Allows you to change the specifications of the field in which you currently are. Change field specs/Other field Change field specs/Other field This option enables you to change any other field on your format. It is particularly useful to change fields you can't get at (Output only fields). Global Colors/Attributes Global Colors/Attributes This option allows you to change the colors/attributes of all fields of a kind (all variables, all constants or all output only fields) on your format. Format/Control Specs Format/Control Specs The same as you have seen already during layout design. Chapter II, SFD getting started page 51 Chapter II, SFD getting started page 51 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Colors/Attributes Colors/Attributes _________________ You now select 'Global Colors/Attributes'. When asked for a field type, select 'Constant'. This means that you want to change the appearance of all Constants in your format. In your case these are the first three fields. Before starting to do any modification, it is important to describe | the meaning of Normal, Active and Selected fields. | What determines if a field is displayed in Normal or Active status is related to your position to this field, in other words, whether you are 'in it' or not; i.e. it becomes active if you go there. | Selected is mainly utilized for Constants (nevertheless it can be useful with other fieldtypes as well for certain effects, see | Appendix A under 'Advanced Programming Technics'). Selected is a boolean status proprietary to a field. In the case of a Constant field it can be toggled by pressing Return while being in the field. To express the above states, field attributes, seperate for monochrome and color screens, can be choose as required. Field Attributes Field Attributes On monochrome displays, some of the field attributes like 'underline' | and 'Inverted' are exclusive. Since Selected can come together with | both Normal and Active field status, it is your responsibility to make sure that the attributes don't exclude each other. As an | example, if you would specify 'Selected' as being inverted and Active as being underlined the appearance of the appropriate field wouldn't change whether you were in the field or not, it would just being inverted in both cases. This could be very irritatating since you might not be able to recognize what field you were in. In the case of 'Color' attributes the same is true for example if you | choose an 'intensified' color for selected and the 'Intens' attribute | for Active. If you have a monochrome adapter, you can't see the results of any changes made to the 'Color' attributes and vice versa. Nevertheless, you should at least read the appropriate chapters. Then try out some combinations of attributes matching the display adapter you are using. Chapter II, SFD getting started page 52 Chapter II, SFD getting started page 52 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Color Screen Attributes Color Screen Attributes | The Normal and Selected Choices are pretty straightforward. You can select any one out of 16 foreground colors and any one out of 8 background colors for each one of the two. Keep in mind, that if you use 'intensive' forground colors you may | get in conflict with the 'Intens' attribute for Active. | The choices you have for Active are: Invert : The foreground color becomes the background color and vice versa. Intensified background colors are not possible. Therefore the non intensified equivalent is being used if necessary. Blink : Self explanatory. The blink frequency can be adjusted. See under 'System Defaults'. Intens : The foreground color is displayed intensified. Multiple choices of the above attributes are possible. Multiple choices of the above attributes are possible. | Now let us specify a 'new look' for the Constants in our format. The foreground and background colors you see are modified as follows: Select the appropriate field. Choose your favourite from the selection you are presented with. Simple, isn't it? | The Active attributes can be set or reset by pressing the Return key. Once you have made your selection, go back to your format. If you have a Color Monitor you will instantly see the results of your modifications. Chapter II, SFD getting started page 53 Chapter II, SFD getting started page 53 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Monochrome Attributes Monochrome Attributes Norm : 'White' text on black where 'White' means the color of the screen you are using (usually green or amber). Intens : Same as 'Norm' but brighter Text. Obviously, 'Norm' and 'Intens' exclude each other. If 'Intens' is used together with 'Invert' text just appears to be 'thinner'. Invert : Black text on 'White' background. Underline : Field will be underlined. 'Underline' and 'Invert'exclude each other. In this case, 'Invert' takes precedence. Marked : Directly before and after the field a triangle pointing towards the field will be displayed. If | 'Marked' is used as an Active attribute the triangles | will blink, if it is used as a Selected attribute they are static. Blink : The field content will blink. The blink frequency can be adjusted. See under 'System Defaults' for details. Multiple choices of above attributes are possible with the exceptions Multiple choices of above attributes are possible with the exceptions mentioned. mentioned. To set/reset monochrome attributes just travel to the appropriate | fields and press Return. Now make your choices. Once you have finished go back to your format you will instantly see the Results of your modifications (at least if you are working on a monochrome monitor). To get some exercise, feel free to venture using other options as well. Maybe you even want to change some other specifications. Just do it and watch the results. Once you are done with the exercises two ways are offered to exit your format. 1. | Fill it out completely and press Return or 2. Hit the ABORT key. Chapter II, SFD getting started page 54 Chapter II, SFD getting started page 54 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Conclusion Conclusion __________ The purpose of this exercise was to give you a brief overview on the Screen Format Designer. Only a small part of the features was Screen Format Designer touched, but you should now have enough knowledge to continue your exploration on your own, using the descriptions later on in this manual. If you should have encountered any difficulties during our exercise or did not get along with the instructions given, I encourage you to just try it again and I am sure you will succeed this time. Anyway, as long as you are not completely familiar with the system | you are urged to make frequent use of the Help feature. Note: If for some reason you accidentally 'scrambled' your address Note: label format during our exercise, don't worry you will find one among the sample programs which came on your distribution disk. Some of them, (including the address label format) will be used later on to give you an idea about SCL and others will be discussed in the SCL Appendix A of this manual to demonstrate some advanced SCL programming technics. Chapter II, SFD getting started page 55 Chapter II, SFD getting started page 55 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Screen Format Designer The Screen Format Designer ( S F D ) ( S F D ) Functional Description Functional Description OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Functional Description - Introduction Functional Description - Introduction | This chapter of the manual provides a functional description of The The | Screen Format Designer Program. Screen Format Designer The first chapter describes the basic program layout. It includes an overview on all files being used or created by SFD as SFD well as the keyboard functions and a description of the Online Help System. The next chapter covers the main menu and all functions accessible from it. The third chapter then talks about Format Design and all related functions. Chapter II, SFD functional description page 57 Chapter II, SFD functional description page 57 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SFD Basic Program Layout SFD Basic Program Layout SFD has been designed around a Main Menu which automatically comes up SFD as soon as the program has been started. All basic functions are shown and accessible from here. They are logically grouped in seven lines. Within each group the most important item is listed first. | The Up and Down keys can be used to jump between the groups and items | in a group are selected with the Right and Left keys. There are two functions on the main menu which are considerably more complex than all others Format layout design and Test. They are virtually subsystems on their own. | Format layout design for example leads through a whole series of screens and functions. It first starts with the actual layout editor. Within the layout editor, many keys have a different meaning compared to normal operation and there are also a lot of special functions available including it's own little menu offering additional features. Once the | Layout editor is left, the Format Specification Mode is entered presenting another local menu with all selections necessary to specify a format and it's fields. | Leaving the Format Specification Mode then finally leads back to the | Main Menu. | The Format Test function is not that complex but it also allows to | enter the Format Specification Mode, in this case via another local menu. This allows a very interactive method of testing a new format. If initial requirements are not met or require to be redefined, the appropriate changes can be performed and verified instantly in a simple iteration. Chapter II, SFD functional description page 58 Chapter II, SFD functional description page 58 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Files used by SFD Files used by SFD In order to run, SFD requires the following files to be present in SFD the same subdirectory as SFD.EXE itself: SFD.FOR: SFD.FOR: SFD's own format file, containing nearly sixty formats. This file is SFD's not exactly compatible with the '<Name>.SCS' files being generated by SFD and no attempt should be made to modify this file using SFD. This SFD SFD could lead to unpredictable results. SFD.FIN: SFD.FIN: Sorted Index file for SFD.FOR. This file is similar to the <Name>.SCS files being generated by SFD and contains informations to access the SFD formats in SFD.FOR. SFD.MSG: SFD.MSG: | Contains all field messages proprietary to SFD. It has the same SFD format as the <Name>.MSG files created by SFD. SFD SFD.ERR: SFD.ERR: | A Text file containing all necessary system messages, i.e all messages required by SCL (as contained in "SCL.ERR") as well SCL additional ones having been especially defined for SFD. SFD SFD.DEF: SFD.DEF: | This file is automatically created if any of the SFD Defaults (Design or System Defaults) are changed and saved. If it is not present, SFD SFD will use its own built in defaults. If for any reason it is desired to go back to default parameters, just remove this file. Chapter II, SFD functional description page 59 Chapter II, SFD functional description page 59 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Files generated by SFD Files generated by SFD Whenever a new work file is opened with SFD, the following files will SFD be created: <workfile>.SCS: <workfile>.SCS: Format file. This file will contain all formats including their specifications with every format occupying about 4.5 KB. The Layout of this file is described in file SCL.DOC as type 'Screen'. For a discussion of it's content refer to "Format Specifications" later in this manual. <workfile>.SCI: <workfile>.SCI: Index (Key) file for <workfile>.SCS. This file contains indexing information to the format file such as all the format names and the relative positions of these formats within <workfile>.SCS. In addition, it also contains informations whether a format is deleted. The layout of this file can be found in SCL.DOC under 'Sckeyrec'. It has to be sorted in order to access formats in a user program via SCL. | This is automatically done whenever you Exit the SFD program. Since SFD the keyfile is very small, sorting it usually takes only a few seconds. <workfile>.MSG: <workfile>.MSG: | Contains all explanatory messages specified for fields on any of the formats in <workfile>.SCS. The format file itself only stores a pointer to these messages. The file consists of records with a length of 71 bytes each (described in SCL.DOC as 'Msgrec'). This leads to a maximum message length of 70 bytes since the first byte of each record is used to store the length of the message. Note: All of the above mentioned files are required by SCL to handle Note: SCL the formats in your <workfile>. Details on how they are used can be found later in this manual under "The Screen Control Language". Chapter II, SFD functional description page 60 Chapter II, SFD functional description page 60 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Basic Keyboard Functions Basic Keyboard Functions The following keyboard functions apply for all formats in SFD. In the SFD layout editor some keys have different functions. For details see under "The Layout Editor". | Right : 1. In Travel Mode : Next Field. Right | 2. In Entry Mode : Next Character. | Left : 1. In Travel Mode : Previous Field. Left | 2. In Entry Mode : Previous Character. Down : First field on next line. Down Up : Last field on previous line. Up Home : First field in line. Home End : Last field in line. End PgDn : Last field on format. PgDn PgUp : First field on format. PgUp Tab : Next field. Tab ShiftTab : Previous field. ShiftTab Backspace : Delete character left of cursor. Backspace Insert : Insert a space at the cursor position. Insert Delete : Delete character under cursor. Delete Return : 1. Entry mode. Return 2. Finish field and advance to next field (if already in the last field, finish the format). | 3. Toggle Selected Status of a Constant. Escape : Finish Format. Escape F1 : Format related Help information. F1 F2 : Field related Help information. F2 F3 : UNDO. Restores field to previous content. F3 F10 : Abort current activity (not valid with everyformat). F10 Note: A detailed explanation of all key functions can be found Note: earlier in this manual under "Getting started". Keys only being valid in certain contexts are mentioned where they apply. Chapter II, SFD functional description page 61 Chapter II, SFD functional description page 61 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Online Help Facility Online Help Facility SFD provides an extensive Online Help Facility in up to four levels SFD as follows: Explanatory field input informations: Explanatory field input informations: This feature is only available with some formats, one being the main menu. SFD automatically displays some informations regarding the SFD currently active field (in the case of the main menu, on the bottom line). AutoHelp: AutoHelp: | Optional feature, selectable via System Defaults which causes some basic Help information to be displayed if a specified number of consecutive input errors have been made. Format Help: Format Help: Context sensitive Help relative to the current format. Can be | accessed anytime by pressing F1. Field Help: Field Help: Context sensitive Help informations relative to the currently active | field. This feature can be accessed anytime by pressing F2. Field Help may not be available in all cases. Chapter II, SFD functional description page 62 Chapter II, SFD functional description page 62 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Input Error Handling Input Error Handling If an Input error is detected, the system reacts with a 'Beep' and, depending on the format, an error message may be displayed. If the | Autohelp feature is enabled and a specified number of consecutive errors has occurred, a format containing some basic help informations is displayed in addition. There are basically three different types of errors which can occur: 1. An invalid key has been pressed. 2. Wrong data has been entered into a field. 3. A field where data entry is mandatory has not been filled in. They are described in the following. Invalid Key Invalid Key Whenever a key is pressed it is checked for validity in the given context. Some examples: | * Entering a displayable character while being in a Constant | field. * Pressing an 'Alpha' key where numeric data is anticipated. * Entering a decimal point if an integer number is required. * Pressing a function key not valid on this format. Wrong data Wrong data Whenever an attempt is made to leave a field (i.e pressing RETURN, TAB or a similar key) the data having been entered into it is checked for validity. Should it be found to be invalid, the user is forced to correct it before he is allowed to leave the field. Missing mandatory data Missing mandatory data Any attempt to leave a format missing mandatory data will be refused. The cursor will automatically be placed into the first field where data was found to be missing. Chapter II, SFD functional description page 63 Chapter II, SFD functional description page 63 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Main Menu The Main Menu The main menu is subdivided into an header, the main body finally, below it, the message line. The Menu Header The Menu Header In it's upper part the program name, the release number and a copyright note are displayed. Below this, there are three lines of information: Act DIR Act DIR Displays the currently active disk and subdirectory. Workfile Workfile Displays name and path of the currently loaded workfile (or '<none>'). Formats Formats The number of valid formats in the current workfile. The Main body The Main body It shows seven groups (lines) of items. On the lefthand side of each line the name of a group of functions is mentioned and the entries to the right of it represent the functions available within the appropriate group. All functions are described in the following paragraphs under their group description in the order they appear on the menu. The Message Line The Message Line A short explanation of the currently highlighted function. Chapter II, SFD functional description page 64 Chapter II, SFD functional description page 64 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual DESIGN DESIGN This Group provides all functions necessary to design a format layout, specify it's parameters and finally to test it. Since this group is amongst the most comprehensive parts of SFD it's functions SFD are covered under an own header ("Format Design") later on in this manual. Chapter II, SFD functional description page 65 Chapter II, SFD functional description page 65 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual FILE FILE There are three functions belonging to this group. Load File: Load File: Load File can not only be selected via the main menu, it also comes up automatically whenever no workfile is loaded and any other function requiring a workfile has been selected. Allows to load a | formatfile as the active workfile and can also be used to change the active workfile. If this Function is selected SFD will ask for the name of the SFD | workfile to be loaded which will then be searched for in the Active | Directory. | Since a format file is always assumed to have an extension of .SCS it is not required to specify it and any extension entered will be ignored by SFD. SFD | If the format file specified exists in the active directory it is then loaded. Otherwise SFD displays a message prompting whether a new file should SFD be created or not. Note that if another format file was loaded before it is automatically saved to disk. In case the specified format file (<workfile>.SCS) was found, exceptions loading it are handled as follows: If no Indexfile (<workfile>.SCI) exists it will be created. If no message file (<workfile>.MSG) is found, SFD offers the option SFD to create a new (empty) one. Please note that in this case all field messages which might have been specified for any formats in the <workfile> will be lost and have to be reentered. CHDir: CHDir This option provides essentially the same services as the equivalent DOS command. | With CHDir you can change the currently active drive and/or subdirectory. A file to be loaded or to be copied from will always be assumed to be | in the Active Directory. Note: The active directory and even the current disk drive can be Note: changed anytime during program execution, even while a workfile is loaded. Since SFD always stores the full path of any file having been SFD loaded, the change of the active subdirectory does not affect it. Therefore, a file is always stored back to the subdirectory it was loaded from. Chapter II, SFD functional description page 66 Chapter II, SFD functional description page 66 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Crunch: Crunch: This function physically removes all previously deleted formats from the active workfile. | Once a Crunch has been performed on a workfile it is not any longer | possible to undelete previously deleted formats. A Crunch reduces the size of the format file by the space previously allocated to the deleted formats (about 4.5 KB per format) and also speeds up subsequent format access. | For these reasons it is recommended to perform a Crunch prior to use a format file in a program. Before SFD attempts to crunch a file, it saves the old version of the SFD format file under the name <workfile>.BAK. This is done in order to provide a backup possibility in case of system errors etc during the actual crunch operation. The index file is not saved since it can easily be rebuild. The following procedure should be applied to recover an old format | file from <workfile>.BAK whenever it is suspected that an error might | have occurred during Crunch and you are not sure about the integrity of the format file : 1. Save the files <workfile>.* on a backup disk and store them safely away. On your work disk, perform the following operations: 2. Delete <workfile>.SCI, the index file. (This index file had been | created to match the crunched version of the format file and is therefore useless at the moment. 3. If present, delete file <workfile>.SCS (the newly generated, crunched format file, which is suspected to be wrong. 4. Rename <workfile>.BAK to <workfile>.SCS. 5. Start SFD and load <workfile> as your workfile. SFD 6. SFD will automagically create a new index file for it SFD (<workfile>.SCI). 7. Check the integrity of the format file by looking at the number of formats and/or printing a format list. Once you are satisfied create a backup copy of <workfile>.* and discard the intermediate backup copy you have made at the beginning of this procedure. 8. You now have backed up to the point before you attempted to | perform the Crunch operation. Chapter II, SFD functional description page 67 Chapter II, SFD functional description page 67 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual FORMAT FORMAT This set of functions deal with copying, deleting and undeleting of formats in the workfile. The meaning of the single items is as follows: Copy: Copy: Duplicates a format under a different name within the workfile. This feature is especially handy if several similar formats are required | for one program. Using Copy to duplicate a master version and change it later on can save considerable time over building every single format from scratch. | If Copy is selected you will be asked for the name of the format to be copied (Origin) and the name under which you want it to be copied | (Destination). Destination must be a name not yet existing in your format file. | Copy (together with Delete) can also be used to change the name of a format by first copying it to the new name and afterwards deleting the old one. Delete: Delete: Deletes a format from the active work file. Delete does not actually remove this format from the file, it is just | marked invalid (logically deleted). This has several advantages, probably the biggest one being that it can still be recovered (undeleted). | Please note that undelete is only possible as long as no Crunch has been performed on the work file. Undelete: Undelete: | Undelete restores a format which had been logically deleted before, | in other words, it can reverse a Delete operation. Before attempting | to undelete a format, make sure that no other format exists with the same name. | The names of all formats capable of being undeleted can be seen by | either printing a Format list or via the Display formats command. Transfer: Transfer: To load a format from a different format file. If this function is selected SFD will ask for both the name of the SFD format file and the name of the format to be loaded. In case both can | be found in your Active directory the format is added under the same | name to your active work file. Note that like in all cases where you are asked for a format file, the name of it is expected to have an | extension of .SCS, any other extension you may specify is masked off. Chapter II, SFD functional description page 68 Chapter II, SFD functional description page 68 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual DISPLAY DISPLAY Formats: Formats: The names of all formats in the current work file are displayed. The | logically deleted formats will be included as well, they are marked as being deleted. Files: Files: | Initiates a display of the names of all format files in the active | directory. Directory: Directory: Provides the same functions as the DOS "Dir" command. A file specification according to DOS rules is expected and all files matching this specification will be displayed. Wild card as well as drive/subdirectory specifications follow the same rules as for the DOS "Dir" command. Chapter II, SFD functional description page 69 Chapter II, SFD functional description page 69 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PRINT PRINT Single format: Single format: Prints a hardcopy of the format specified, accompanied by a description of its fields, on the active printer. If the printer is not ready or out of paper, such a status will be reported back to you and you are given the option to either correct the situation or abort the print. Note that in order to work correctly the printer must be capable to print the upper half of the character set according to IBM standard. All formats: All formats: Similar to above, but prints hardcopies of all valid formats in the active work file. Format list: Format list: Prints a listing of the most important details of all formats in the active work file. These are : Format name, size of the format, total number of fields, cursor home | position, the related help format and information whether the format is deleted or not. A summary is also added. It lists the total number of formats in the file as well as the number of valid and deleted formats. Chapter II, SFD functional description page 70 Chapter II, SFD functional description page 70 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual DEFAULTS DEFAULTS The two functions in this group allow to inquire or change of SFD's SFD's program default specifications. If changed, the Option is given to save the new defaults in a disk file (SFD.DEF) to be automatically used again with any subsequent run of SFD until they become altered again. If the option is choosen not SFD to save the new defaults, they will only be valid for the current program run. Design: Design: Left Field Limit: Left Field Limit: The character to be interpreted as the left limit of a field, i.e whenever this character is found, SFD assumes that a field is about SFD to start at the next character position. The default setting of this parameter is '['. Right Field Limit: Right Field Limit: The character indicating the end of a field. The field ends at the character position ipreceeding the Right Field Limit Character. The default is ']'. Note: For detailed informations on how to use the field limit Note: | characters refer to Basic Format Layout Design. later on in this manual. Background Color: Background Color: One among eight colors to be used as background during format layout design. The default is 'Blue'. Foreground Color: Foreground Color: One among sixteen colors to be used as foreground (text) color during format layout design. The default is 'light grey'. Note: The above two color options only apply when a color graphics Note: | adapter is used. On systems using a Monochrome adapter, the Design | Background Color is always "Black" and the foregound color is "White" (i.e the color of your screen). Chapter II, SFD functional description page 71 Chapter II, SFD functional description page 71 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Surrounding Area: Surrounding Area: | Used by the Layout Editor. If a format layout work area is defined to be smaller than a full screen, the surrounding (unused) area is filled with the character specified here. The default setting for this option is Character Ascii (Hex) 'FA' (a dot). Note: For more information on how to enter special characters see Note: Appendix A, 'Tips and Tricks'. Chapter II, SFD functional description page 72 Chapter II, SFD functional description page 72 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual System defaults System defaults The following parameters can be altered: The following parameters can be altered: Auto Help: Auto Help: SFD can be configured to automatically come up with Help information SFD if a certain number of consecutive input errors have occurred. 'Yes' is the default setting and indicates that this feature is | enabled. If 'No' is selected, Auto Help is disabled. After n Errors: After n Errors: | Specifies the number of consecutive errors after which the Auto help screen is to be displayed. Please note, that if consecutive errors are identical they are counted double i.e. the second and all following occurrences are counted twice. The Default is '3'. Beep yes/no: Beep yes/no: Determines whether SFD 'beeps' in case of errors. SFD If 'no' is selected, SFD will stay quiet. SFD The default setting is 'Yes'. Length (ms): Length (ms): Duration of the 'beep' tone in milliseconds. The default is 200. Pitch (Hz): Pitch (Hz): Every 'beep' is made up of several short bursts of two alternating frequencies which can be freely specified. A Sound using a single frequency can be selected by setting both frequencies to the same value. The frequencies must be between 100 and 9999 Hz. The default settings are 200 Hz for the first and 350 Hz for the second frequency. Field Blink Frequency: Field Blink Frequency: SFD allows to select the frequency a field is blinking. This figure SFD is expressed in milliseconds and determines the delay to wait before inverting the field color again. Chapter II, SFD functional description page 73 Chapter II, SFD functional description page 73 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Char YES: Char YES: The Ascii code of the upper case letter indicating 'Yes', i.e. in the case of english '89' ('Y'). Char NO: Char NO: Same as above for 'No', i.e in the case of english '78' ('N'). Note: The above two options are used in the case of 'boolean' Note: fields. These fields only allow either one of above characters to be entered. Lower case characters are automatically translated. Cursor Wraparound Disabled: Cursor Wraparound Disabled: If this option is set to 'Yes' then Cursor Wraparound is disabled for | all formats in SFD. This Option is especially beneficial if a Mouse SFD is utilized to operate SFD. SFD | Provided Cursor Wraparound is not disabled, pressing Right or Down while being in the last field of a format moves the cursor to the | first field. The opposite happens if Left or Up is pressed while being in the first field of a format. Please note, that even if cursor wraparound may not be disabled it is not available with all formats in SFD. SFD Chapter II, SFD functional description page 74 Chapter II, SFD functional description page 74 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual EXIT EXIT Terminate Program: erminate Program: If a workfile was loaded it is automatically sorted before SFD SFD terminates. This is necessary to make the formats within this workfile accessible for SCL routines. SCL Note: SCL cannot be used with unsorted format files. Any attempt to Note: SCL do so will result in a fatal error aborting the appropriate program. Chapter II, SFD functional description page 75 Chapter II, SFD functional description page 75 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Design Format Design _____________ Basic Work Flow Basic Work Flow The basic flow of developping a new format is as follows: The basic flow of developping a new format is as follows: 1. Design of the basic format layout. 2. Specification of all fields. 3. Global specifications. 4. Determination of colors & attributes. 5. Test of the format and necessary changes. Note: This sequence only represents a crude guideline. Note: Except for step 1, SFD does not impose restrictions on the sequence SFD these actions have to be performed. In practice, you will find that some steps can sometimes be omitted completely since SFD's default SFD's settings are often sufficient. On the other hand you may find that some activities have to be performed more than once in order to achieve the desired results. Initially, steps 1 through 4 should always be performed via the main | menu item Layout Design. Beside a few restrictions, steps 2 to 4 can also be carried out using | the Format test facility with the added advantage that results of changes become immediately visible. | However, since changes are much more convenient within the layout | design system it is advisable to perform all major specification work there and use the test facility only to carry out minor corrections found necessary while testing the format. Chapter II, format design page 76 Chapter II, format design page 76 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Layout Editor The Layout Editor The Layout editor is activated by selecting the first item on the | Main Menu, "Layout Design". First, SFD will ask for the name of the SFD format to load. In case this format exists, it is loaded and displayed, otherwise SFD gives you the option to create a new format SFD with the specified name. The Layout editor provides a worksheet to develop or change a format layout as well as to specify size and location of its fields. Formats in the layout editor are displayed in a slightly different | fashion than under Test or if they are used in a SCL application SCL program: * All fields are shown with Left and Right delimiters (Default: '[' and ']'). * The Cursor has the shape of a big block and can be moved freely across the whole format. * If the format is smaller than a full screen (80 X 25) then the area outside the format is filled with the characters specified | for this purpose in Design Defaults. In addition some keys do have other meanings than in normal formats. Note: If the Layout editor has been instructed to create a new Note: format, SFD assumes by default that it's size is 25 lines with 80 SFD characters each (a full screen). This is the reason why the whole screen is initially erased in order to serve as a drawing board. Chapter II, format design page 77 Chapter II, format design page 77 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Layout editor Meaning of keys Layout editor Meaning of keys | Backspace, Insert and Delete have the same meaning as under normal Backspace Insert Delete operation, but they do work on a full line instead of in a field. Home moves the cursor to the upper left corner of your worksheet. Home | End moves the cursor to the first character of the last line. End | PgUp deletes the line under the cursor. PgUp | PgDn inserts a line. PgDn | Return moves the cursor to the first character of the next line. Return | The Arrow keys allow the cursor to move freely on the format. | The Arrows are working in wrap-around mode as follows: The Arrows are working in wrap-around mode as follows: Right with the cursor being in the rightmost position moves it to the first position of the next line. Left with the cursor being in the first position of a line moves it to the last position of the previous line. Right while being in the lower right corner of the worksheet moves the cursor to the upper left corner. Left while being in the upper left corner moves the cursor to the lower right corner of the worksheet. | Pressing Up while being in the first line moves the cursor to the | last line and the opposite happens with Down while in the last line. Note: All Special key functions belonging to the layout editor are Note: discussed later on in this chapter together with the actions they perform. Chapter II, format design page 78 Chapter II, format design page 78 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Drawing Fields Drawing Fields | All desired fields in a format must be determined within the Layout | Design phase. To describe their position and length two special characters are | defined in SFD: The Left Field Delimiter (LD) and the Right Field | Delimiter (RD). The default values are '[' for LD and ']' for RD. These values can be | changed to any other character via Design Defaults. A LD determines the begin of a field. SFD always assumes that a field SFD begins at the character position immediately following an LD. It also assumes that it ends at the position immediately before a RD. A field must always end on the same line it begun, i.e it may not continue on the next line. In order to allow consecutive fields with only one character position between them, it is possible to omit the RD character. In this case, the LD is interpreted as the termination of a field at the position preceeding it and also as the start of a new field at the position succeding it. However you should note that the last field on any line has still to be terminated with an RD character. According to this, all the examples below represent valid field constructions. (The line below the actual delimiters shows the range of each field as described by the delimiters in form of 'x' characters). [ ] [ [ [ ][ ] xxxxxxxx xxxxxxxxx xxxxxxxx xxxxxxxxx xxxxxxxxx Chapter II, format design page 79 Chapter II, format design page 79 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Special Functions Special Functions In order to facilitate the process of developing a format layout, the Layout Editor offers a whole range of special functions. Although very versalite, they can be activated using very few different keys. The ones that are most frequently used are directly accessible via function keys. Some other, less often used functions can be called up via a small menu which itself is accessible with a function key. The appropriate Function keys are as follows: The appropriate Function keys are as follows: F4 : Delete Block F5 : Mark Block Corner F6 : Copy Block F7 : Undraw Box (or line) F8 : Draw Box F9 : Menu Functions The following paragraphs will discuss all special functions in logical sequence. Chapter II, format design page 80 Chapter II, format design page 80 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Mark Corner (F5) Mark Corner (F5) | Many of the layout editors special functions are so called Block | Functions. | Before any of these Block Functions can be performed it is necessary to important to describe the rectangular area (block) they should act | upon. This is done by simply marking its two diagonal corners. A block does not necessarily have to be two-dimensionall it can also | be a line or a column of any desired length. In these cases just mark both ends of it. Pressing F5 sets a mark at the cursor position, shown as a small F5 rhombus. | Incidentally set Marks can simply be removed again by positioning the | cursor on them and pressing F5 again. Notes: Only a maximum of two marks may be set at any time, any Notes: additional attempt is refused. Marks are automatically removed as | soon as the Block Function is performedn Copy Block (F6) Copy Block (F6) | Pressing F6 will duplicate the marked block at the current cursor F6 position (Building it's upper left corner). Please note that for obvious reasons it is not possible to copy a block into itself, in | other words to a cursor position enclosed by the marked Block. If the block to be copied is bigger than the space available at the cursor position, the parts which do not fit are automatically truncated. Delete Block (F4) Delete Block (F4) | F4 erases the marked Block, in other words, moves spaces to it. This F4 function can also be used to erase the whole worksheet by marking its two corners. Chapter II, format design page 81 Chapter II, format design page 81 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Draw Box (F8) Draw Box (F8) | Pressing F8 causes a box to be drawn with the two marks representing F8 its diagonal corners. The linestyles used for both horizontal and vertical lines can be | selected via the local menu (for further details refer to "Local Menu Functions"). When using single or double lines graphic characters the proper connections to other boxes will be done automagically. Beside for drawing boxes, this function can also be used to draw lines by positioning the two marks in either the same column (vertical line) or the same row (horizontal line). Undraw box (F7) Undraw box (F7) Erases the marked box, i.e replaces it by space characters. The same | rules apply as for the Draw Box Function. Chapter II, format design page 82 Chapter II, format design page 82 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Menu Functions Menu Functions The menu can be accessed by pressing F9. It offers the following F9 functions: Change Format size Change Format size This function allows to change the size of the currently loaded format layout. Valid sizes can be anything from 1 to 25 lines with 1 to 80 characters each. Boxes Linestyles Boxes Linestyles This function facilitates the selection of the linestyles to be used | with the Box drawing feature. Possible linestyles are displayed in two groups, one for horizontal and one for vertical lines. Each of them can be determined independently. Each group contains the following: 1. Double Line Block Graphics characters. 2. Single Line Block Graphics characters. 3. White half Blocks. 4 to 6: Full Blocks in different shades. 7. Any other character, see Text below. For the first two Options (Single and Double line block graphic characters), SFD is even capable to connect boxes using the SFD appropriate 'X' and 'T' elements available in the Character set. The last Option is used to choose any other displayable character. If selected, another format comes up showing an extract of 32 characters at a time out of the complete system characterset. The | Left and Right keys can then be used to point to the desired character or to select another set of 32 Characters to choose fromn | Once the desired character is found just press Return to pick it. Using this feature boxes and/or lines made up for example of smiling faces or $-signs can easily be created. Chapter II, format design page 83 Chapter II, format design page 83 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Key Redefinition Key Redefinition This function allows to assign any desired keyboard key to any displayable character. It becomes very handy if certain Characters are required in a format which can not normally be accessed with a keyboard key. The selection of the appropriate character to be displayed works in a | similar fashion as the one above described for User selectable | linestyles. Up to six keyboard keys can be redefined at the same time. Note: There exists also another possibility to display characters Note: normally not accessible via the keyboard which is described in Appendix A under 'Tips and Tricks'. Chapter II, format design page 84 Chapter II, format design page 84 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Specifications Format Specifications All format specification parameters are stored in the actual format file (<Name>.SCS). | Once a new format has been designed and the Layout Editor is exited, all these parameters will be set to default values, i.e every field is assumed to be a variable, there is no input check to be performed, the color of the format is white on a black background and so on. These specifications can then be tailored to your own requirements. When an existing format is modified, SFD where format specifications SFD | can be changed. The main one is directly after the layout Editor has been exited and the other one, which is slightly limited in some | aspects is accessible via a local menu during Format Test. Two main groups of specifications exist: Field Specifications Field Specifications The specifications defining a single field on a format. Global Specifications Global Specifications All specifications proprietary to the whole format. Not only are the format specifications directly accessible and alterable but it is also possible to copy field specifications from another field or to change colors and attributes of a whole group of fields such as all variables or all constants on a format. | Note: Some parameters cannot be modified during Format Test, where Note: this is the case, it is mentioned in the following. The discussion of the format specifications is subdivided under three headings: * Field Specifications * Colors and Attributes * Global Specifications and Control Parameters Chapter II, format design page 85 Chapter II, format design page 85 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Field Specifications Field Specifications Type Type Defines the field type. This parameter cannot be modified during | Format Test. The possible choices are: Variable: A normal data entry field.This is the default. Variable | Constant: A selectable item (for example in a menu). Constant Output : Output A field not accessible by the cursor (for example a message line). Group from/to Group from/to | Important for Constants. All Constants within one group are exclusive, i.e. only one field within a group can be selected at any one time. Enter the numbers of the first and the last field of the group. The default is the current field for both values. These parameters have no meaning for fields other than constants. If the field specifications for the first field of a group are modified, they are automatically copied to all other fields of that group. The only parameters not being copied are: 'Selected' and 'Messages. | This parameter can not be modified during Test. Message Message A message can be specified for each field on a format. It is stored | in file <Name>.MSG and automatically displayed in the Message field (see under 'Global Specifications'). There are also some other possibilities to use this message, see Appendix A under 'Advanced Programming Technics'. The default is no message. Helpscreen Helpscreen | The name of the format to display if the Field help Key, usually 'F2' is pressed. The default is no helpscreen. Fill Fill Variables only. The character to replace all spaces with if the field | is active. The default is <Space>. Chapter II, format design page 86 Chapter II, format design page 86 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Delimiter Left Delimiter Left | The character to display at the position where the Left field | delimiter was put during Layout Design, i.e the character position preceeding the field. The default is <space>. Delimiter Right Delimiter Right | The character to display at the position where the Right field | delimiter was put during Layout Design, i.e the position immediately after the field. The default is <space>. Justify Justify Determines how text within the field is to be justified. The possible choices are 'Left', 'Right' and 'Center'. The default is 'Left'. Decimals Decimals Numeric variables onlyn Determines how many positions are to be displayed after the decimal point. The default is 0 (zero). Mandatory Mandatory Determines whether input is mandatory to this field. In case of | constants it determines whether a selection within the Group has to be made. The default is 'No'. Selected Selected Determines the initial status of the boolean attribute 'Selected'. It usually applies to constants but it can also be used for some special effects like highlighting etc. See Appendix A under 'Advanced Programming Technics' for details. The default status is 'No'. Note that this attribute cannot be copied to other fields. Char Check Char Check If this parameter is set to 'Yes', each single keystroke can be externally checked, i.e SCL hands over control to your application SCL after each keystroke before actually acting on it. For details on the use of this parameter see the description of the SCL procedure SCL 'Handle_Format' later on in this manual. Additional hints can be found in Appendix A (Sample Programs, especially Sample 4). The default for this parameter is 'No'. Chapter II, format design page 87 Chapter II, format design page 87 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Input Check Input Check Variables only. Determines the kind of data to be accepted as valid input in this field. The possibilities are as follows: None: No input check is performed. Any data may be entered in None this field. This is the default. Integer: Only integer numbers may be entered. Any other input is Integer refused. The numeric value entered must be within the limits of 'Min' to 'Max' (see below). The maximum possible range is -32768 to +32767. Fields where entries outside this range are required must be declared as 'Real' (see below). Real: Any number with or without a decimal point can be entered. Real It's value must be in the range of 'Min' to 'Max' (see below). It is not possible to enter numbers in scientific notation. Alpha: Only alpha characters are allowed in this field. Other Alpha input is refused. | Y,y,N,n: Only the characters defined as Boolean_Yes and Y,y,N,n | Boolean_No (both lower and upper case) may be entered in this field. For Details see the explanation of these two SCL routine SCL upon the initialisation of the program. This feature makes it possible to define optimum formats without any compromises. Chapter II, format design page 88 Chapter II, format design page 88 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Monochrome Attributes Monochrome Attributes Normal: The way the field should appear if it is neither 'active' nor Normal 'selectedg. The possible choices are white characters on a black background (Norm) or white intensified characters on a black background (Intens). The default is 'Norm'. Selected: The way the field should look if it is 'Selected' (see Selected above). The possible choices are: Invert : Black text on white background. Underl : Text underlined. Intens : Intensified textn Marked : Two triangles are displayed to the left and the right of the field. Combinations of above attributes are possible with the following exceptions: Invert and Underline are exclusive. Invert and Intensified result in Invert only. Active: The way the field should be highlighted if the cursor is in Active it. Possible choices are: Invert : The field is inverted. Underl : Underlined text. Intens : Intensified text. Marked : Two blinking triangles are displayed to the left and the right of the field. Blink : The field blinks. Combinations of the above attributes are possible with the same | exceptions as the ones mentioned for the Selected attributes. Since | the Active attributes are just 'added' if the field becomes active (for example, a constant can be both 'selected' and 'activeg at the same time) careful consideration should be given the question what combination of attributes should be used. If for example the same attributes are choosen for both 'active' and 'selected' it may not be possible to see, in which field the cursor is (in the case of 'marked', there is a differentiation because the triangles blink if the field is active). In addition, restrictions apply to the combined use of 'Invert' together with 'Underline' or 'Intens'. The result is always 'Invert' only. Chapter II, format design page 89 Chapter II, format design page 89 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Color Attributes Color Attributes The Color Attributes are less complicated to use than the monochrome ones. For both 'Normal' and 'Selected' there is a choice of one out of eight background colors and one out of sixteen foreground (text) colors. All available colors are listed in Appendix B. As far as the 'Active' attribute is concerned there are three different options. Invert: The field colors are inverted, i.e background becomes Invert: foreground and vice versa. Since intensified background is not possible, these colors are replaced by their non intensified (i.e. darker) counterpart. Blink : The field is made blinking. Blink : Intens: The text is displayed intensified. Intens: The combination of the above options is possible but it should be considered that the 'Intens' attribute is only meaningful if the foreground colors choosen for 'Normal' and 'Selected' are non intensified ones, otherwise it won't be visible. Chapter II, format design page 90 Chapter II, format design page 90 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Global Specifications Global Specifications & Control Parameters & Control Parameters Global Specifications Global Specifications Cursor Home: Cursor Home: System generated and not changeable. The first cursor accessible (non Output) field on the format. Input Message Field: Input Message Field: The field where all Input Messages are to be displayed (Input Messages are the messages specified for single fields, see under 'Field Specifications' for details). If this Parameter is set to 0 (zero) no input messages are displayed. Note that for obvious reasons, the field specified for input messages should be an 'Output' field, i.e. not be accessible by the cursor. The default for this parameter is 0. Error Message Field: Error Message Field: The field where all (system as well as user generated) error messages | are displayed. Everything said above for the Input Message Field applies here as well. If this field is set to 0 (zero) no error messages are displayed. There are no restrictions to use the same field for both error and input messages. The default is 0 (zero) i.e no error messages are displayed. Help Format: Help Format: | The name of the format to be displayed if the Format Help Key (usually 'F1') is pressed. The default is no help format. Color Foreground: Color Foreground: One out of sixteen colors in which the text on the format (except for the fields) is to be displayed. This option is only meaningful in the case of Color screens. On monochrome screens, the foreground color is always white, non intensified. Color Background: Color Background: One out of colors in which the format background (except for the fields) is to be displayed. For monochrome screens, the format background is always black. Chapter II, format design page 91 Chapter II, format design page 91 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Cursor Wraparound: Cursor Wraparound: | If Cursor Wraparound is disabled, pressing Right or Down while the | cursor is in the last field or Left or Up while the cursor is in the first field causes a beep. Otherwise, the cursor would be advanced to the first or last field, respectively. Note: Alternatively, Cursor Wraparound can also be disabled on a Note: global basis, i.e effective for all formats in a program by setting the SCL Constant 'No_Wrap' to TRUE. Refer to the SCL part of this SCL SCL manual for more details. Format Abort Ok Format Abort Ok | If this option is set to 'Yes', pressing the F10 key causes the | format to be unconditionally terminated, otherwise the Abort function is disabled for this format. Chapter II, format design page 92 Chapter II, format design page 92 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual User Function Keys User Function Keys The User Function Key specifications control SCL's user interrupt SCL's system. This facility allows to invoke user written routines upon certain occasions while the format is being handled by SCL routines. SCL Details and examples on how to use them can be found in both the SCL SCL part of this manual and in Appendix A. In principle they work as follows: When a specified condition occurs, the SCL procedure SCL 'Handle_format' notifies an external procedure and gives it the choice to do whatever it is intended for (like a special input check for example). This external procedure can also return a result indicating an error or a exception to cause 'Handle_format' to proceed in the desired way. By default, i.e. without the need to be explicitly specified, SCL SCL allows you to invoke external procedures whenever a new field is entered with the cursor, when it is being left and when the format is due to be exited. Beside what is mentioned above it is possible to specify optional | User Function Keys for any format. User Function keys can be any of the ten actual Function keys (F1 to F10) and additionally to this up to ten other keyboard keys. F1 through F10: F1 through F10: If selected, causes 'Handle_format' to transfer control whenever the corresponding function key has been pressed. There are numerous uses for these Interrupts like the initiation of program functions or to temporarily disable SCL functions like 'Help' etc. SCL Remaining fields: Remaining fields: Up to ten different keyboard keys can be defined per format which, when pressed, cause 'Handle_format' to transfer control. 'Keyboard keys' in this context can also be combinations like 'CNTRL-LEFT' etc. | To define a key as a User Function move the cursor to one of the | fields containing the text '<deleted>' and press Return. Then press | the key or key combination you want to specify. To delete a User | function Key specification, just position the cursor on it and hit | Return. | Chapter II, format design page 93 Chapter II, format design page 93 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Test Feature The Test Feature Introduction Introduction SFD allows new formats to be tested without having to write a user SFD | program. With very few limitations, formats under Test react exactly as they later on will in a user program. This even includes input checks etc. While a format is being tested, it is possible to modify most of it's specifications and instantly observe the results of these changes, thus allowing for a very interactive way of developing formats. The local Menu The local Menu | All functions to modify Format Specifications during Test are available through a local menu which can be called up by pressing key 'F9'. It offers the following choices: Change Field Specifications/Active Field Change Field Specifications/Active Field Allows to change the specifications of the field the cursor is currently in. Change Field Specification/Other Field Change Field Specification/Other Field This Option is mainly intended but not limited to allow to change 'Output' fields. If choosen, SFD will ask for the number of the field SFD whose specifications are to be changed. Change Global Colors/Attributes Change Global Colors/Attributes Allows to change Colors or attributes of all fields of a type to be | specified (Variable, Constant or Output) on the format under Test in one go. Change Format/Control Specifications Change Format/Control Specifications Allows to change the Global Specifications as well as the Interrupt Parameters. Chapter II, format design page 94 Chapter II, format design page 94 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual System Limitations System Limitations The SFD Format Test Feature has a few limitations. These are: SFD Speed Speed Since rather than reading from memory as it normally would be done by SCL much information has to be read from disk, thus slowing down the SCL | operation of a format under Test quite considerably. Help Formats Help Formats It is not possible to access the Help formats specified for the | format under Test via F1 and F2. They have to be tested seperately. | F1 and F2 display SFD's own help information relative to Test SFD's operations. Format Specifications Format Specifications | Some specifications can not be altered during Test. These include: Field Type, Group from/to and Input and error message fields. In order to change these specifications the format has to be loaded into | the Layout Editor and the changes have to be performed there. Chapter II, format design page 95 Chapter II, format design page 95 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual This Page is intentionally left blank Chapter II, format design page 96 Chapter II, format design page 96 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Chapter III Chapter III OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual This Page is intentionally left blank Chapter III, Screen Control Language page 98 Chapter III, Screen Control Language page 98 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Screen Control Language Screen Control Language ( S C L ) ( S C L ) Chapter III, Screen Control Language page 99 Chapter III, Screen Control Language page 99 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Introduction Introduction ____________ The Screen Control Language The Screen Control Language SCL is accommodated in several TURBO PASCAL Source Library files SCL which must be 'included' in your application programs in order to access the constructs they contain. The following is a functional description of all relevant constructs | contained in these Include Files. For more details on SCL, including explanations and samples available SCL in Appendix A. Chapter III, Screen Control Language page 100 Chapter III, Screen Control Language page 100 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Files SCL Files The following is a brief description of all SCL files. SCL SCL.TPU : SCL.TPU : Contains all SCL definitions and routines. All elements of SCL can be SCL accessed from your Turbo Pascal 4 program by specifying SCL in the USES statement. Example: Example USES CRT,SCL,PRINTER; SCL.ERR : SCL.ERR : This is a basic Error Message File for your programs and contains all SCL internal error messages. Its use is explained later in this manual. Chapter III, Screen Control Language page 101 Chapter III, Screen Control Language page 101 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL - Global Declarations SCL - Global Declarations General General | Many of SCL's Global Constants are actually declared as typed Global Constants | constants. This was done to allow their alteration during program runtime. | Despite all their advantages, Typed Constants in TURBO PASCAL also have one slight disadvantage: Since they are are only initialized once, i.e at the time the program is loaded into memory, irritating effects can occur if an application program is compiled to memory and afterwards run from there more than once. For this reason it is recommended to compile programs using SCL to a SCL '.EXE' file on disk in order to test them. | The following chapters describe most of the Global Declarations | forming part of SCL, starting with the Global Constants and | Variables and followed by those Type declarations which could be of use outside SCL as well. SCL Chapter III, Screen Control Language page 102 Chapter III, Screen Control Language page 102 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Control Parameters SCL Control Parameters The following parameters define the maximum size of files etc. Their default settings are layed out in such a way that they should be sufficient in most cases. They can cater for up to: 100 Error Messages. 400 Field (explanatory) Messages. 20 Formats displayed simultaneously. Looking at these figures you can see that only some special, usually very large applications may require parameter changes. Max_Error_Messages Max_Error_Messages Declaration: CONST Max_Error_Messages = 100; Explanation: The highest allowed user message number. This constant must be set to a value equal to or greater than the number of records in file <workfile>.ERR. The default setting allows for about 60 additional user messages, since approximately 40 records are already occupied with system error messages. Max_Input_Messages Max_Input_Messages Declaration: CONST Max_Input_Messages = 400; Explanation: | Contains the maximum number of Field Messages. This constant must be set to a value equal to or greater than the number of records in file <workfile>.MSG which can be calculated as follows: (Size of file <workfile>.MSG (in bytes) divided by 71) + 1. Remark: In order to allow for later changes to your formats it is recommended to increase the minimum number calculated as above by at least 50 %. Max_Heap_Screens Max_Heap_Screens Declaration: CONST Max_Heap_Screens = 20; Explanation: The maximum number of formats which can be 'stacked' one on top of the other on the display. Chapter III, Screen Control Language page 103 Chapter III, Screen Control Language page 103 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual File Names File Names The following constants define what file name extensions SCL expects. SCL While it is recommended to leave them at their default settings (i.e compatible with SFD), it is still possible to change them if required. In this case the files created by SFD must be renamed before they can be used with the appropriate application. In any case, make sure that you don't use extensions which do have special meanings in your system like '.BAK' (backup file) or '.PAS' (Pascal source file). Screenfile_Ext Screenfile_Ext Declaration: CONST Screenfile_Ext = '.scs'; Explanation: File name extension used for the format file. Change if a different extension is desired. Indexfile_Ext Indexfile_Ext Declaration: CONST Indexfile_Ext = '.sci'; Explanation: File name extension to be used for the format index file. Change if a different extension is to be used. Errorfile_Ext Errorfile_Ext Declaration: CONST Errorfile_Ext = '.err'; Explanation: File name extension to be used for the file containing the system and user error messages. Change if a different extension is to be used. Messagefile_Ext Messagefile_Ext Declaration: CONST Messagefile_Ext = '.msg'; Explanation: File name extension to be used for the file containing the field messages. Change if a different extension is to be used. Chapter III, Screen Control Language page 104 Chapter III, Screen Control Language page 104 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Help System Parameters Help System Parameters Autohelp_Screen Autohelp_Screen Declaration: CONST Autohelp_Screen = 'autohelp'; Explanation: | The name of the format to be used for the Autohelp feature. Change if another format is to be used. Maxerrors Maxerrors Declaration: CONST Maxerrors : INTEGER = 3; Explanation: If 'Autohelp_Set' is true, this value determines the number of | consecutive errors before the Autohelp format is displayed. Auto_Help_Set Auto_Help_Set Declaration: CONST Auto_Help_Set : BOOLEAN = TRUE; Explanation: | If this parameter is TRUE , the Auto_Help feature is enabled, i.e the | format specified as Autohelp_Screen is displayed automatically | whenever Maxerror consecutive input errors have been made. If it is | set to FALSE, the Auto_Help feature is disabled. Code_Help_Field Code_Help_Field Declaration: CONST Code_Help_Field : INTEGER = 1060; Explanation: | The key used to display the Help Format declared for the currently active field. Code_Help_Format Code_Help_Format Declaration: CONST Code_Help_Format : INTEGER = 1059; Explanation: | The key used to display the Help Format declared for the currently active format. Note: For information on how keyboard keys are coded see under Note: | Keyboard Key Specifications. Chapter III, Screen Control Language page 105 Chapter III, Screen Control Language page 105 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Beep Parameters Beep Parameters The following parameters allow to change pitch and duration of the | Beep, i.e. the sound SCL uses in order to attract the users attention SCL because of input errors etc. Beep_Off Beep_Off Declaration: CONST Beep_Off : BOOLEAN = FALSE; Explanation: If set to TRUE SCL will not 'beep' in case of errors. SCL Beep_Time Beep_Time Declaration: CONST Beep_Time : INTEGER = 3; Explanation: Duration of the 'beep' in clock ticks (55 ms). Beep_Frequency_1 Beep_Frequency_1 Declaration: CONST Beep_Frequency_1 : INTEGER = 200; Explanation: First frequency used for the 'beep' sound in hertz. The 'beep' consists out of two alternating frequencies. Beep_Frequency_2 Beep_Frequency_2 Declaration: CONST Beep_Frequency_2 : INTEGER = 350; Explanation: Second frequency used for the 'beep' sound in hertz. The 'beep' consists out of two alternating frequencies. Chapter III, Screen Control Language page 106 Chapter III, Screen Control Language page 106 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Message Display Message Display The following two parameters can be used to allow different, user selectable 'Help' levels. Input_Msg_Set Input_Msg_Set Declaration: CONST Input_Msg_Set : BOOLEAN = TRUE; Explanation: | If set to FALSE, no Field Messages will be displayed. Can be used to suppress explanatory messages with experienced users. Error_Msg_Set Error_Msg_Set Declaration: CONST Error_Msg_Set : BOOLEAN = TRUE; Explanation: If set to FALSE, no messages will be displayed in case of input | errors. SCL will however still 'beep' as long as Beep_Off is FALSE. SCL Chapter III, Screen Control Language page 107 Chapter III, Screen Control Language page 107 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Field Attributes Field Attributes The following specifications define the blink frequency for constants (see 'Blink' field attribute) as well as what characters are used for the 'Marked' field attribute. Blink_Count Blink_Count Declaration: CONST Blink_Count : INTEGER = 0; This count is incremented each clock tick. A clock tick occurs about 18.2 times per second (every 55 ms). Blink_count can be interogated by user routines. Timer_Intervall Timer_Intervall Declaration: CONST Timer_Intervall : INTEGER = 4; Explanation: Used as a delay for the field blinking procedure. Determines the delay after which the fieldcolor is inverted again. Decrease for faster and increase for slower blinking. Mark_Field_Left Mark_Field_Left Declaration: CONST Mark_Field_Left : Byte = 16; Explanation: | The ASCII code of the character used as the Mark on the left side of the field (see 'Marked' field attribute). Mark_Field_Right Mark_Field_Right Declaration: CONST Mark_Field_Right : Byte = 17; Explanation: | The ASCII code of the character used as the Mark on the right side of the field (see 'Marked' field attribute). Chapter III, Screen Control Language page 108 Chapter III, Screen Control Language page 108 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Key Specifications Key Specifications The values of all keyboard keys associated with functions are defined as constants in order to be able to adapt programs to non standard keyboards. Their values are calculated as follows: 1. Use the decimal ASCII code of the key to perform the appropriate function. 2. | Add 1000 in case this key creates an extended code, i.e one preceeded by an 'ESC' character. Code_Cancel_Act Code_Cancel_Act Declaration: CONST Code_Cancel_Act : INTEGER = 1061; Explanation: The key used to cancel a change to a 'variable' and to restore the original content of it (Default:F3). Modify in case you want some key to perform this action. Code_Abort Code_Abort Declaration: CONST Code_Abort : INTEGER = 1068; Explanation: The the key to unconditionally terminate the current format in case the 'Abort Ok' attribute is set to 'Yes' in its Global specifications. Code_Escape Code_Escape Declaration: CONST Code_Escape : INTEGER = 27; Explanation: The key to terminate a format. Chapter III, Screen Control Language page 109 Chapter III, Screen Control Language page 109 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Performing 'Edit' functions Performing 'Edit' functions CONST Code_Home : INTEGER = 1071; CONST Code_Tab : INTEGER = 9; CONST Code_Ctrltab : INTEGER = 1116; CONST Code_Rtab : INTEGER = 1015; CONST Code_Return : INTEGER = 13; CONST Code_Left : INTEGER = 1075; CONST Code_Right : INTEGER = 1077; CONST Code_Down : INTEGER = 1080; CONST Code_Up : INTEGER = 1072; CONST Code_End : INTEGER = 1079; CONST Code_Ins : INTEGER = 1082; CONST Code_Del : INTEGER = 1083; CONST Code_Backspace : INTEGER = 8; CONST Code_Pgup : INTEGER = 1073; CONST Code_Pgdown : INTEGER = 1081; Function Keys Function Keys | The following are the codes of the keys associated with the Function | Key Interrupts (see 'Global Format Specifications'). Change as required for non standard keyboard layouts. CONST Code_F1 : INTEGER = 1059; CONST Code_F2 : INTEGER = 1060; CONST Code_F3 : INTEGER = 1061; CONST Code_F4 : INTEGER = 1062; CONST Code_F5 : INTEGER = 1063; CONST Code_F6 : INTEGER = 1064; CONST Code_F7 : INTEGER = 1065; CONST Code_F8 : INTEGER = 1066; CONST Code_F9 : INTEGER = 1067; CONST Code_F10 : INTEGER = 1068; Chapter III, Screen Control Language page 110 Chapter III, Screen Control Language page 110 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Nationalisation Parameters Nationalisation Parameters The following declarations determine the message to be displayed in case of a fatal program abort initiated by SCL. Change for other languages as required. CONST Fatal_Msg_1 = 'FATAL SCL ERROR: '; CONST Fatal_Msg_2 = 'ERROR NR: '; CONST Fatal_Msg_3 = 'PROGRAM ABORTED.'; | The following two parameters define the valid input for Boolean | Variables. Change according to the language used. Code_Yes Code_Yes Declaration: CONST Code_Yes : INTEGER = 89; Explanation: The first letter of the word meaning 'Yes' in upper case (Y). Used | for Boolean Fields. Change for other languages. Code_No Code_No Declaration: CONST Code_No : INTEGER = 78; Explanation: The first letter of the word meaning 'No' in upper case (N). Used for | Boolean Fields .Change for other languages. Character sets for Variables Character sets for Variables The following constants define the characters permitted to be entered into the various types of Variable fields. Change as required for national character sets. CONST Anything_Set : SET OF Byte = [1..6,8,14..27,32..255]; CONST Integer_Set : SET OF Byte = [32,43,45,48..57]; CONST Real_Set : SET OF Byte = [32,43,45,46,48..57]; CONST Alpha_Set : SET OF Byte = [32,65..90,97..122,128..167]; Chapter III, Screen Control Language page 111 Chapter III, Screen Control Language page 111 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Country Information Parameters Country Information Parameters SCL_Country SCL_Country Declaration: CONST Scl_Country : INTEGER = 0; Explanation: The country information to be used for SCL. If this parameter is set to 0 (zero) SCL uses the country specified in the computers CONFIG.SYS file. If another countries informations are to be used set this constant to the appropriate value. (Example : 49 for germany). The country codes available are described in your DOS manual under the COUNTRY command. SCL interrogates the Country informations during initialization and sets up the following variables accordingly: Country Country Declaration: VAR Country : INTEGER; Explanation: Contains the country code of the country currently being used by SCL. SCL This is either the Country code specified in CONFIG.SYS or if 'SCL_Country' (see above) is set to a value other than 0 (zero) it is set equal to this. Date_Format Date_Format Declaration: VAR Date_Format : INTEGER; Explanation: Determines the date format being assumed by SCL's date formatting and check routines. 0 means MMDD and 1 means DDMM format. Date_Separator Date_Separator Declaration: VAR Date_Separator : CHAR; Explanation: The character to be used as a separator between days, months and year by SCL's date formatting routines. Chapter III, Screen Control Language page 112 Chapter III, Screen Control Language page 112 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Time_Separator Time_Separator Declaration: VAR Time_Separator : CHAR; Explanation: The character to be used as a separator between hours and minutes by SCL's time formatting routines. Currency Currency Declaration: VAR Currency : String10; Explanation: Contains the name or symbol of the currency of the country being assumed by SCL (see above). Note: Since SCL's own date and time formatting routines are using Note: the above informations, they automatically adapt to different countries and don't therefore have to be nationalized manually. The same principle should be applied to user written application programs wherever possible. Chapter III, Screen Control Language page 113 Chapter III, Screen Control Language page 113 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Control Parameters SCL Control Parameters Progpath Progpath Declaration: VAR Progpath : String80; Explanation: Progpath holds the complete path description (including Drive) of the subdirectory which was active when SCL was initialized, i.e at the time, the procedure 'Select_Format_File' was called. SCL remembers this subdirectory because it expects to find its files there, even if the active subdirectory was changed during program execution. This variable is quite useful to find other, non SCL files if they reside in the same directory as the program itself. Example: Example: Assumed a program using SCL is started from directory '\Appl\Mydir' on drive C. If SCL has been initialized then 'Progpath' contains the following information: 'C:\Appl\Mydir\'. The statement 'Assign(myfile,Progpath + Example.Fil)' now will assign the following file name to 'Myfile': c:\Appl\Mydir\Example.Fil Note: The information contained in 'Progpath' must not be changed. Note: No_Wrap No_Wrap Declaration: CONST No_Wrap : BOOLEAN = FALSE; Explanation: | If No_Wrap is set to false, the cursor wraparound feature is controlled individually for each format by its global attribute 'Wraparound Ok'. | In case No_Wrap is set to TRUE, this will override the appropriate specifications and cursor wraparound will therefore be disabled for all formats. This Option has been provided to adapt SCL written applications SCL easily to 'Mouse' operation. | If a program is operated with a keyboard Cursor Wraparound can be very helpful, especially on large formats. On the other hand , if a | 'Mouse' is being used, Cursor Wraparound can be very confusing. | No_Wrap allows to choose the optimum in both cases. Chapter III, Screen Control Language page 114 Chapter III, Screen Control Language page 114 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Pointers Format Pointers S_Ptr S_Ptr Declaration: VAR S_Ptr : INTEGER; Explanation: S_Ptr controls the format stack and always points to its top, i.e to the currently active format. If a format is loaded to the Heap by | Select_Format, S_Ptr is incremented and once the format is finished | it is decremented by Format_Done. | If S_Ptr is 0 (zero) after Format_Done has decremented it this means that all formats have been finished and the screen is therefore cleared. Other values indicate that there are still one or more formats on the | stack which have not yet been finished. The one S_Ptr is now pointing to is therefore restored and its handling can continue where it was interrupted before. Note: For more details on the above matter refer to 'SCL Procedures Note: and functions' later in this manual. R_Ptr R_Ptr Declaration: VAR R_Ptr : INTEGER; Explanation: | R_Ptr is a Variable mainly used by the routines R_Cont, G_Cont, R_Sel | and G_Sel. It points to the format to be read from. R_Ptr is adjusted equal to | S_Ptr by the routine Handle_Format. This means, R_Ptr will still point to a format, even if this format is not any longer active. For a detailed description of this mechanism refer to the description of the above mentioned procedures. Chapter III, Screen Control Language page 115 Chapter III, Screen Control Language page 115 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual W_Ptr W_Ptr Declaration: VAR W_Ptr : INTEGER; Explanation: | W_Ptr is mainly used by the routines W_Cont, C_Cont and W_Sel. It points to the format currently being written to W_Ptr is normally | equal to S_Ptr. This means that Format fields can be written into as | soon as the format has been loaded by Select_Format and as long as it | has not been finished by Format_Done. For a detailed description of this mechanism see Appendix A. Chapter III, Screen Control Language page 116 Chapter III, Screen Control Language page 116 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Handling Parameters Format Handling Parameters | Many of the following parameters are intended to be used in User | Interrupt Procedures during format handling. Detailed descriptions and examples of user interrupt handling procedures can be found in Appendix A. Active_Field Active_Field Declaration: VAR Active_Field : INTEGER; Explanation: Active_Field always points to the field being processed by | Handle_Format. If a format has no fields, 'Active_Field' is equal to 0 (zero). This Variable can be interrogated by user procedures, typically | during User Interrupt handling. Char_Code Char_Code Declaration: VAR Char_Code : INTEGER; Explanation: Char_Code contains the input character last fetched from the keybuffer by Handle_Format. Handle_Format User interrupt procedures can interrogate or modify 'Char_Code'. If, for example in case of a User Function Key Interrupt the statement User Function Key Interrupt 'Char_Code:=Code_Noop' is executed, Handle_Format then ignores this key. Glb_Error Glb_Error Declaration: VAR Glb_Error : INTEGER; Explanation: This Variable is used by external procedures normally invoked by User User Interrupts to return an error description to 'Handle_Format'. Interrupts In case the external procedure returns a value other than 0 'Handle_Format' initiates an error routine using the error message to which 'Glb_Err' points. Chapter III, Screen Control Language page 117 Chapter III, Screen Control Language page 117 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Handling Parameters Format Handling Parameters The following variables are intended to be interrogated by user written SCL interrupt handling procedures to determine the type of interrupt having occurred. They are all controlled by the procedure Handle_Format. Handle_Format Refer to Appendix A for more details on how to use them. User_Function User_Function Declaration: VAR User_Function : BOOLEAN; Explanation: This variable is TRUE whenever either a User Function Key was User Function Key depressed or any other key was hit during input to a field with the 'CharInt' parameter set to TRUE. For details on the above mentioned parameters refer to 'Format Specifications' in the SFD part of this manual. SFD Begin_Of_Field Begin_Of_Field Declaration: VAR Begin_Of_Field : BOOLEAN; Explanation: This variable is TRUE whenever a new field is due to be entered. End_Of_Field End_Of_Field Declaration: VAR End_Of_Field : BOOLEAN; Explanation: This variable is TRUE whenever a field is due to be left and after all SCL internal checks specified for the appropriate field have been successfully completed. Chapter III, Screen Control Language page 118 Chapter III, Screen Control Language page 118 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual End_Of_Format End_Of_Format Declaration: VAR End_Of_Format : BOOLEAN; Explanation: This variable is TRUE whenever a format is due to be left and after all SCL internal checks have been successfully completed. Please notice that the Abort feature bypasses this interrupt. Abort Checkrequired Checkrequired Declaration: VAR Checkrequired : Boolean; Explanation: At the time of a End_Of_Field interrupt, 'checkrequired' is true if End_Of_Field the field has been changed and false if it hasn't. 'Checkrequired' should be interrogated by an external field input check procedure to find out whether a check has to be done or not. For further information see Appendix A under 'User Interrupt Procedures'. Chapter III, Screen Control Language page 119 Chapter III, Screen Control Language page 119 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Screen related Parameters Screen related Parameters The following variables can be interrogated by user programs but should always be left unchanged. Screen_Mode Screen_Mode Declaration: VAR Screen_Mode : Byte; Explanation: Screen_Mode holds information about what display adapter the computer is currently working with and what mode it is in. Since SCL only works in 80 column text mode, the possible values of Screen_Mode and Screen_Mode their meaning are: 2 : CG Adapter; 80 Columns Text ; No Color. 3 : CG Adapter; 80 Columns Text ; With Color. 7 : Monochrome (or Hercules) Adapter; 80 Columns Text. Mono_Adapter Mono_Adapter Declaration: VAR Mono_Adapter : BOOLEAN; Explanation: Mono_Adapter is true whenever the computer is using the Monochrome Adapter. The status of 'Mono_Adapter' decides to which display memory address SCL writes. Color_True Color_True Declaration: VAR Color_True : BOOLEAN; Explanation: Color_True is set if Screen_Mode is equal to 3. Screen_Mode The status of Color_True determines which set of field attributes is to be used. Chapter III, Screen Control Language page 120 Chapter III, Screen Control Language page 120 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format related Parameters Format related Parameters Xoff Xoff Declaration: VAR Xoff : INTEGER; Explanation: Xoff holds the horizontal offset of the currently active format. If for example Xoff is equal to 5, then the upper left corner of the currently active format starts at column 6 on the screen. Yoff Yoff Declaration: VAR Yoff : INTEGER; Explanation: Yoff holds the vertical offset of the currently active format. If for example Yoff is equal to 3, then the upper left corner of the currently active format starts at row 4. Chapter III, Screen Control Language page 121 Chapter III, Screen Control Language page 121 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Background Processing Parameters Background Processing Parameters LP_Background_Pointer LP_Background_Pointer Declaration: VAR LP_Background_Pointer : POINTER; Explanation: This Variable is a pointer to the procedure to be invoked by SCL as the low priority background task. Example: Example The following statement would cause SCL to perform Myproc as background task: LP_Background_Pointer:=@Myproc; HP_Background_Pointer HP_Background_Pointer Declaration: VAR HP_Background_Pointer : POINTER; Explanation: This Variable is a pointer to the procedure to be invoked by SCL as the high priority background task. Example: The following statement would cause SCL to perform Myproc as high priority background task: HP_Background_Pointer:=@Myproc; Note: SCLs background tasking feature is explained in detail in Note: Appendix A. Chapter III, Screen Control Language page 122 Chapter III, Screen Control Language page 122 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Miscellaneous Parameters Miscellaneous Parameters Glb_Status Glb_Status Declaration: VAR Glb_Status : INTEGER; Explanation: This Variable is a status count controlling the procedure 'Handle_Format' and carries Information about the present status of the format handling process. There is normally no need to interrogate Glb_Status itself, since SCL provides a comprehensive set of Boolean Glb_Status SCL variables for this purpose. Please refer to 'Format Handling Parameters' for details. Glb_Status should not be changed by user routines. Glb_Ok Glb_Ok Declaration: VAR Glb_Ok : BOOLEAN; Explanation: Glb_Ok is set to FALSE by some SCL procedures and functions to flag errors during their execution. It can be interrogated by user programs to make sure that these procedures did not encounter problems during their execution. Details of the conditions under which Glb_Ok is set to FALSE can be found in the descriptions of the appropriate procedures and functions. Format_Aborted Format_Aborted Declaration: VAR Format_Aborted : BOOLEAN; Explanation: A boolean variable which is set to TRUE by the procedure Handle_Format to indicate to succeding procedures that a format has Handle_Format been terminated via the Abort key and that they should therefore Abort key ignore the data having been entered so far into this format (and which is likely to be incomplete, anyway). Chapter III, Screen Control Language page 123 Chapter III, Screen Control Language page 123 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Global Type Declarations Global Type Declarations The following SCL TYPE declarations are not limited to SCL, they are TYPE of rather universal use in a TURBO PASCAL program and can be used in other parts of the application program as well. More type declarations inluding the declarations for the SCL files can be found SCL in the file SCL.DOC. TYPE String128: STRING[128]; TYPE String80 : STRING[80]; TYPE String70 : STRING[70]; TYPE String40 : STRING[40]; TYPE String20 : STRING[20]; TYPE String13 : STRING[13]; TYPE String10 : STRING[10]; Chapter III, Screen Control Language page 124 Chapter III, Screen Control Language page 124 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Procedures and Functions Procedures and Functions Introduction Introduction The following chapters describe all SCL procedures and functions intended to be accessed by user programs in logical sequence. While the routines described here actually only represent a small fraction of the total number of the SCL routines being available, they will enable you to perform all necessary operations. If you are an experienced SCL programmer, you may come along a occasion where you want to access a low level routine directly for some reason. While nothing is actually preventing you from doing so, you should take extreme care not to interfere with SCL. In addition, be aware that most of these low level routines are, usually for performance reasons, not protected against invalid parameters and may therefore cause runtime errors if you pass such data to them. As a general rule, don't use any undocumented SCL routines unless you As a general rule, don't use any undocumented SCL routines unless you really know exactly what you are doing. really know exactly what you are doing. Note: In Appendix B you can find a complete alphabethic list of all Note: SCL routines together with brief comments on their purpose and restrictions. Chapter III, Screen Control Language page 125 Chapter III, Screen Control Language page 125 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Entering and leaving SCL Entering and leaving SCL PROCEDURE Select_Format_File(Filename:String10); PROCEDURE Select_Format_File(Filename:String10); This procedure should be the first SCL routine performed in a program. It first checks the present screen mode to ensure that it is one of the 80 character text modes. Then it opens the screenfile indicated by 'Filename' (<Filename>.SCS) as well as the Index file (<Filename>.SCI) belonging to it. The index file is checked in order to ensure that it is sorted. Then the field message file (<Filename>.MSG and, if available, the error message file (<Filename>.ERR) are loaded into the Heap. Finally some SCL variables are initialized and the screen is cleared. If errors are encountered during this process, SCL halts the program and displays a message indicating the reason for the abort. Note: The parameter 'Filename' must be specified without extension. Note: It is recommended to set the screen mode to the desired value using the Turbo Pascal Construct 'TextMode' before SCL is initialized since SCL aborts the program if the mode is wrong. PROCEDURE Close_Formats; PROCEDURE Close_Formats; This procedure is the last SCL routine to be performed in a program. It frees all space previously occupied by SCL in the Heap, closes the Heap screen files, clears the screen and finally restores the cursor to its normal shape. On the next page you find an example of the basic skeleton of a program using SCL routines. Chapter III, Screen Control Language page 126 Chapter III, Screen Control Language page 126 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Structure of a SCL Program Structure of a SCL Program PROGRAM EXAMPLE; USES SCL; {make SCL accessible} {User declarations, procedures and functions } BEGIN; {of main body of program example} Select_Format_File('exforms'); {This is the first SCL statement in any program. It loads the necessary files and initializes SCL.} {main program} Close_Formats; {Last SCL statement in any program. It closes all SCL files and clears the screen} END; {of main body of program example} Chapter III, Screen Control Language page 127 Chapter III, Screen Control Language page 127 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Loading and displaying formats Loading and displaying formats PROCEDURE Select_Format(Fname:String10); PROCEDURE Select_Format(Fname:String10); Select_Format is the first procedure to be called in order to display and handle a format. It reads the description of the format indicated by 'Fname' from the format file and loads it into memory. If another format is currently being processed and not yet finished, its status is saved in the stack for later recovery once 'Fname' has been finished. Since 'Select_Format' modifies the 'W_Ptr' to point to the new format, its fields can now be 'prefilled' if necessary. PROCEDURE Display_Format(Xoffset,Yoffset:INTEGER); PROCEDURE Display_Format(Xoffset,Yoffset:INTEGER); Once a format has been 'selected' using procedure 'Select_Format' it is displayed on the screen with 'Display_Format'. In addition to display the format, all its fields are initialized according to their specifications and the cursor is placed into the first accessible field (Cursor Home). If there is no field on the format, the cursor is made invisible. Display_Format requires two parameters: Xoffset and Yoffset. They define where on the screen the upper left corner of the new format is to be positioned. Both values are zero based, since they specify offsets counted from the upper left corner of the screen rather than absolute positions. Therefore if for example Xoffset is specified as Xoffset '10' and Yoffset as '0' the format will be displayed with it's upper left corner at Row 1 (the first row), Column 11. Example: Example PROCEDURE Bring_Up_Myformat; BEGIN; Select_Format('Myformat'); {Loads 'Myformat' into Memory} Display_Format(0,0); {displays it starting at the upper left} END; {corner of the screen} Chapter III, Screen Control Language page 128 Chapter III, Screen Control Language page 128 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Note: It is user responsibility to ensure that the space specified Note: by Xoffset and Yoffset is large enough to hold the format to be Xoffset Yoffset displayed. If the space specified is found to be to small, a 'Fatal Error' halting the program will result. Therefore it is recommended to preferably use the functions 'X_Max' and 'Y_Max' wherever possible to specify offsets. For details see overleaf. Chapter III, Screen Control Language page 129 Chapter III, Screen Control Language page 129 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual X_Max and Y_Max X_Max and Y_Max FUNCTION X_Max:INTEGER; FUNCTION X_Max:INTEGER; Returns a value equal to 80 the width of the currently selected format. This function is intended to be used together with the 'Display_Format' Procedure. FUNCTION Y_Max:INTEGER; FUNCTION Y_Max:INTEGER; Returns a value equal to 25 the height of the currently selected format. This function is intended to be used together with the 'Display_Format' Procedure. Examples: Examples Display_Format(X_Max,1); Display_Format(X_Max,1); Displays the format in the upper right corner of the screen. Display_Format(X_Max div 2,Y_Max); Display_Format(X_Max div 2,Y_Max); Displays the format on the bottom of the screen and horizontally centered. Display_Format(1,Y_Max); Display_Format(1,Y_Max); Displays the format in the lower left corner of the screen. Display_Format(X_Max div 2,Y_Max div 2); Display_Format(X_Max div 2,Y_Max div 2); Displays the format centered on the screen. Display_Format(X_Max-3,Y_Max -2); Display_Format(X_Max-3,Y_Max -2); Displays the format wit it's lower right corner positioned on line 23, column 77. Chapter III, Screen Control Language page 130 Chapter III, Screen Control Language page 130 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Handling format input Handling format input PROCEDURE Handle_Format; PROCEDURE Handle_Format; This routine can be seen as the kernel of the SCL System. It's basic purpose is to obtain keyboard input and act upon it. Besides this, it also manages a variety of other important functions such as: * Cursor control. * Input checks according to field specifications and display of error messages. * Display of Help screens and explanatory messages. * Formatting and display of field input. * Control of field attributes according to specifications. * User interrupt recognition and handling. * Invoking of background tasks. Note: 'Handle_Format' is always called in form of a REPEAT....UNTIL Note: REPEAT....UNTIL loop. An example is given at the end of the description of 'Format_Done' on the next page. FUNCTION Format_Done:BOOLEAN; FUNCTION Format_Done:BOOLEAN; This Function is used together with the procedure 'Handle_Format' described above in a REPEAT....UNTIL Loop. REPEAT....UNTIL It checks whether the format currently being handled is finished and, if this is the case, it then terminates it. This means: It also sets the color of the first and last line as well as the first and last column of the format to Backgroundcolor if it was Backgroundcolor highlighted before (see 'Display_Format'). It then it checks for the presence of another format waiting on the stack to be reactivated (one which had not been finished before) and, if this is the case, restores the parts of the screen which had been overwritten. Then all pointers are adjusted to this format and its handling is carried out from where it was interrupted before. If there was no format waiting on the stack to be reactivated, the screen is then cleared. Note: The complete principle of SCL's format stacking is described Note: in Appendix A (Sample 3). Chapter III, Screen Control Language page 131 Chapter III, Screen Control Language page 131 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example: Example REPEAT HANDLE_FORMAT; {Here optional User Interrupt handling statements could be inserted} UNTIL FORMAT_DONE; The above represents the basic construct of any SCL format input handling procedure. The REPEAT....UNTIL loop will be left as soon as the (boolean) REPEAT....UNTIL function 'Format_Done' detects that the format had been finished (In this case, 'Format_Done' returns TRUE). Whenever a User Specified Interrupt (see under 'Format User Specified Interrupt Specifications' in the SFD part of this manual) comes up, the SFD procedure 'Handle_Format' is exited and the user is given the chance to take over control via appropriate statements within the REPEAT....UNTIL loop as indicated in the above example. Since REPEAT....UNTIL 'Format_Done' always returns FALSE as long as the format is not finished, 'Handle_Format' will be reentered once the user specified procedures have been performed. Note that due to this construction the specification of user interrupt handling procedures is optional; even if interrupts have actually been specified for the appropriate format. Chapter III, Screen Control Language page 132 Chapter III, Screen Control Language page 132 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Format Handling Control Format Handling Control PROCEDURE Blank_Format; PROCEDURE Blank_Format; This procedure causes the space the currently handled format occupies on the screen to be cleared (filled with spaces). PROCEDURE Goto_Field(Fieldnr:INTEGER): PROCEDURE Goto_Field(Fieldnr:INTEGER): This Procedure can be used during in a User Interrupt Procedure User Interrupt Procedure (End_of_Field) to jump to another field on the format. It is your responsibility to make sure that the field number to jump to is valid and not declared as Output Only. Output Only PROCEDURE Finish_Format(Check:BOOLEAN); PROCEDURE Finish_Format(Check:BOOLEAN); This procedure is used to terminate the currently displayed format while it is being processed by 'Handle_Format', usually depending on a condition being checked within a User Interrupt Procedure. It User Interrupt Procedure causes 'Handle_Format' to react in exactly the same way as if an appropriate keyboard key would have been pressed. Terminate_Format requires a boolean argument which decides in what way the format is to be finished. If 'Check' is FALSE, it will be terminated unconditionally in a similar way as if the 'ABORT' key would have been pressed. If 'Check' is true, 'Handle_Format' will react as if 'ESCape' would have been pressed. This means, before actually terminating the format it is checked whether all mandatory fields are filled in and the termination is refused if this should not be the case. Notes: Terminating a format unconditionally with the above procedure Notes: works even in case Abort_OK is set to FALSE for this format. Please Abort_OK remark also, that Format_Aborted is not set to TRUE. Format_Aborted Detailed examples of how to handle formats including User Interrupt User Interrupt Procedures can be found in Appendix A under 'SCL Programming Procedures examples'. Chapter III, Screen Control Language page 133 Chapter III, Screen Control Language page 133 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Reading/Writting Format Fields Reading/Writting Format Fields Introduction Introduction In order to read and write both the (boolean) status of the 'selected' attribute as well as the actual content of format fields several SCL routines are provided. The following routines serve to access the field content: The following routines serve to access the field content: R_Cont: R_Cont: 'Read field content'. A procedure to read the content of a field into a string variable. G_Cont: G_Cont: 'Get field content'. Similar to above, but in form of a function. W_Cont: W_Cont: 'Write field content'. A procedure to write the content of a string variable to a field. C_Cont: C_Cont: 'Clear field content'. A procedure to clear a field i.e to fill it's content with spaces). | The following routines serve to access the Selecte attribute of The following routines serve to access the Selecte attribute of format fields: format fields: R_Sel: R_Sel: 'Read field selected status'. A procedure to read the status of the 'selected' attribute into a boolean variable. G_Sel: G_Sel: 'Get field selected status'.Similar to 'R_Sel' but in form of a boolean function. W_Sel: W_Sel: 'Write field selected status'. Sets the status of the 'selected' attribute to the desired value. Note: A detailed description of these routines can be found on the Note: following pages. Chapter III, Screen Control Language page 134 Chapter III, Screen Control Language page 134 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Reading Field Content Reading Field Content PROCEDURE R_Cont(Fieldnr:INTEGER; VAR Contents:String80); PROCEDURE R_Cont(Fieldnr:INTEGER; VAR Contents:String80); This procedure acts on the format pointed to by 'R_Ptr'. It reads out the content of field 'Fieldnr' and puts it left justified into 'Contents'. Note that the content of the field is always returned in form of a string, even in the case of numeric variables. In case the value in 'Fieldnr' does not represent a valid field or 'R_Ptr' does not point to a valid format an empty string (length = 0) is returned and 'Glb_Ok' is set to FALSE. Example: R_Cont(2,Mystring); Example: R_Cont(2,Mystring); The content of the second field of the format pointed to by 'R_Ptr' is returned in 'Mystring'. Note: R_Ptr normally either points to the format in process or to Note: the one that was last processed by 'Handle_Format'. Therefore, as long as 'Handle_Format' has not been performed on a new format, the last one is still accessible, even after it is 'finished' (in this case however only as long as no new format has been loaded with 'Select_Format'). If no format has been processed yet or if the format last having been processed was overwritten by a new one (it was finished and 'Select_Format' has been called) 'R_Ptr' contains 0 (Zero) and any attempt to read a field now would result in in a 'Fatal SCL Error' halting the program. For detailed information on the above refer to Appendix A. FUNCTION G_Cont(Fn:INTEGER):String80; FUNCTION G_Cont(Fn:INTEGER):String80; This Function calls the procedure 'R_Cont'. Therefore the statement Mystring:=G_Cont(2) is equivalent to R_Cont(2,Mystring). The use of 'G_Cont' instead of 'R_Cont' often leads to more elegant constructs and better readable programs. It can also save in many cases the declaration of local variables. The two (functionally identical) examples on the next page may illustrate this. Chapter III, Screen Control Language page 135 Chapter III, Screen Control Language page 135 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Examples for R_Cont and G_Cont Examples for R_Cont and G_Cont Example 1 (using R_Cont): Example 1 (using R_Cont): PROCEDURE Read_Format; VAR Wrkstr:String80; {TYPE String80 is defined as STRING[80]} BEGIN; R_Cont(1,Surname); {Read the content of field 1 to 'Surname'} R_Cont(2,Forename); {Field 2 to 'Forename'} R_Cont(3,Wrkstr); {Field 3 to 'Wrkstr'} City:=Capital(Wrkstr); {Change 'Wrkstr' to upper case and} END; {store it in 'City'.} Example 2 (using G_Cont): Example 2 (using G_Cont): PROCEDURE Read_Format; BEGIN; Surname :=G_Cont(1); {Read the content of field 1 into 'Surname'} Forename:=G_Cont(2); {Field 2 to 'Forename'} City:=Capital(G_Cont(3)); {Field converted to uppercase and END; {stored in 'City'.} Chapter III, Screen Control Language page 136 Chapter III, Screen Control Language page 136 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Writing Field Content Writing Field Content PROCEDURE W_Cont(Fieldnr:INTEGER;Cont:String80); PROCEDURE W_Cont(Fieldnr:INTEGER;Cont:String80); This procedure works on the format pointed to by 'W_Ptr'. It writes the string 'Cont' to the field indicated by 'Fieldnr'. If 'Fieldnr' doesn't point to a valid field no action is performed and 'Glb_Ok' is set to FALSE. If 'Cont' does not completely fit into the field it is cut off at the appropriate length and 'Glb_Ok' is set to false as well. Note that since W_Cont expects a string value, numeric information has to be W_Cont converted first. In case the format being written to is currently displayed, the appropriate field content is changed on the screen as well. Example: Example: PROCEDURE Prefill; VAR Wrkstr : String80; A_String : String80; {Info to be written to field 1} A_Real_Number : REAL; {Info to be written to field 2} A_Integer_Number : INTEGER; {Info to be written to field 3} BEGIN; A_String :='This is a string'; {Initialize} A_Real_Number :=1.234; {our silly } A_Integer_Number:=67; {examples } W_Cont(1,A_String); {Writes 'A_String' to field 1} STR(A_Real_Number,Wrkstr); {Converts it to a string...} W_Cont(2,Wrkstr); {...and writes it to field 2} W_Cont(3,St(A_Integer_Number); {uses the SCL Function 'St'..} END; {..to convert it to a string and writes it to field 3.} {Note:'St' can only be used to convert 'INTEGER values} Note: W_Ptr is initially set by the procedure 'Select_Format' and Note: keeps on pointing to this format until it is finished. Detailed information on 'W_Ptr' can be found in Appendix A. Chapter III, Screen Control Language page 137 Chapter III, Screen Control Language page 137 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Deleting Field Content Deleting Field Content PROCEDURE C_Cont(Fieldnr:INTEGER); PROCEDURE C_Cont(Fieldnr:INTEGER); This procedure 'clears' the field indicated by 'Fieldnr'. It is equivalent to: W_Cont(Fieldnr,' '). Everything having been said under W_Cont(Fieldnr,' ') 'W_Cont' applies to 'C_Cont' as well. Example: Example: C_Cont(1); {Clears field 1, i.e. writes spaces to it.} Chapter III, Screen Control Language page 138 Chapter III, Screen Control Language page 138 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Reading the 'Selected' Attribute Reading the 'Selected' Attribute PROCEDURE R_Sel(Fieldnr:INTEGER; VAR Sel:BOOLEAN); PROCEDURE R_Sel(Fieldnr:INTEGER; VAR Sel:BOOLEAN); This procedure acts on the format pointed to by R_Ptr. This procedure returns in 'Sel' the status of the Selected attribute Selected of the field identified by 'Fieldnr'. In case the value in 'Fieldnr' does not represent a valid field or 'R_Ptr' is not pointing to a valid format 'Glb_Ok' is set to FALSE. For further information on 'R_Ptr' refer to the description of 'R_Cont'. Example: Example: R_Sel(2,Status); R_Sel(2,Status); After performing this operation, 'Status' will be TRUE if the second field of the format pointed to by 'R_Ptr'is Selected. Selected FUNCTION G_Sel(Fn:INTEGER):BOOLEAN; FUNCTION G_Sel(Fn:INTEGER):BOOLEAN; This function calls the procedure R_Sel. Therefore the construct Status:=G_Sel(2) is equivalent to R_Sel(2,Status). In many cases, the use of 'G_Sel' in favour of 'R_Sel' can not only save the declaration of local variables but also allow more elegant constructs. The following two (functionally identical) examples illustrate this. Example 1 (using R_Sel): Example 1 (using R_Sel): R_Sel(1,Mrs); R_Sel(2,Miss); Female:= Mrs or Miss; Example 2 (using G_Sel): Example 2 (using G_Sel): Female:=Gsel(1) or gsel(2); Chapter III, Screen Control Language page 139 Chapter III, Screen Control Language page 139 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Writing the 'Selected' Attribute Writing the 'Selected' Attribute PROCEDURE W_Sel(Fieldnr:INTEGER;Sel:BOOLEAN); PROCEDURE W_Sel(Fieldnr:INTEGER;Sel:BOOLEAN); This procedure works on the format pointed to by 'W_Ptr'. It sets the 'Selected' attribute of the field indicated by 'Fieldnr' to the boolean value of 'Sel'. If 'Fieldnr' doesn't point to a valid field no action is performed and 'Glb_Ok' is set to FALSE. In case the format being written to is currently displayed, the appropriate field is changed to reflect the status of the 'selected' attribute on the screen as well. Example: Example: W_Sel(5,TRUE); {Marks Field 5 to be 'selected'} Note: W_Ptr is initially set by the procedure 'Select_Format' and Note: keeps on pointing to this format until it is finished. For detailed information on 'W_Ptr' refer to Appendix A. Chapter III, Screen Control Language page 140 Chapter III, Screen Control Language page 140 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual String Handling routines String Handling routines FUNCTION Capital(Wrkstr: String): String; FUNCTION Capital(Wrkstr: String): String; This function returns the input string converted to uppercase letters. Example: Example: Mystring:=Capital(Mystring); If Mystring was ' aBc' it becomes ' ABC'. FUNCTION Stripleft(Wrkstr: String): String; FUNCTION Stripleft(Wrkstr: String): String; Returns the input string with all leading spaces stripped off. Example: Example: Mystring:=Stripleft(Mystring); If Mystring was ' ABC ' it becomes 'ABC '. FUNCTION Stripright(Wrkstr: String): String; FUNCTION Stripright(Wrkstr: String): String; Returns the input string with all trailing spaces stripped off. Example: Example: Mystring:=Stripright(Mystring); If Mystring was ' ABC ' it becomes ' ABC'. Chapter III, Screen Control Language page 141 Chapter III, Screen Control Language page 141 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE Strip(VAR Wrkstr:String;VAR Len:INTEGER); PROCEDURE Strip(VAR Wrkstr:String;VAR Len:INTEGER); Removes all leading and trailing spaces from Wrkstr and returns it's resulting length in len. Example: Example: Mystring:=' ABC '; Strip(Mystring,Stlen); After performing the above statements, Mystring equals 'ABC' and Stlen equals 3. FUNCTION Charstring(Whatchar:CHAR;Len:INTEGER):String; FUNCTION Charstring(Whatchar:CHAR;Len:INTEGER):String; Returns a string of length = Len, completely filled with Whatchar. Example: Example: Mystring:=Charstring('A',5); Mystring now contains 'AAAAA'. PROCEDURE Frontstring(Str:String; VAR Head,Tail:String); PROCEDURE Frontstring(Str:String; VAR Head,Tail:String); Returns the first word of 'Str' in 'Head' and the remainder in 'Tail'. In both cases, leading blanks are stripped off. Word separators can be one or more blanks. If 'Str' only contains one word, 'Tail' is returned with a length of 0 (zero). Example: Example: Var S1, S2 :String; Begin; Frontstring('This_is.a-Frontstring 'This_is the tail ',S1,S2); End; S1 now contains 'This_is.a-Frontstring' and S2 contains 'This_is the tail '. Please notice that trailing spaces in the tail are not removed. Please notice that trailing spaces in the tail are not removed. Chapter III, Screen Control Language page 142 Chapter III, Screen Control Language page 142 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual FUNCTION Justify_Left(STR:String;Len:INTEGER):String; FUNCTION Justify_Left(STR:String;Len:INTEGER):String; Returns the input string justified left in a field of length Len. The remaining part of the field is filled up with spaces. If the input string was, after the leading and trailing spaces were removed, still longer than len, it is cut off at len. In this case, Glb_Ok is set to false. Example 1 : Example 1 : Mystring:=' abc '; Mystring:=Justify_Left(Mystring,5); After execution, Mystring is equal to 'abc '. Example 2 : Example 2 : Mystring:=' abc '; Mystring:=Justify_Left(Mystring,2); In this example, Mystring would be returned as 'ab' and Glb_Ok would be false. FUNCTION Justify_Right(STR:String;Len:INTEGER):String; FUNCTION Justify_Right(STR:String;Len:INTEGER):String; Returns the input string justified left in a field of length Len. with the part before the text being filled up with spaces. If the input string without leading and trailing spaces is longer than len, it is cut off at len. In this case, Glb_Ok is set to false. Example 1: Example 1: Mystring:=' abc '; Mystring:=Justify_Right(Mystring,5); This example returns Mystring = ' abc'. Example 2: Example 2: Mystring:=' abc '; Mystring:=Justify_Right(Mystring,2); Mystring would now be equal to 'ab' and Glb_Ok would be false. Chapter III, Screen Control Language page 143 Chapter III, Screen Control Language page 143 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual FUNCTION Justify_Center(STR:String;Len:INTEGER):String; FUNCTION Justify_Center(STR:String;Len:INTEGER):String; Returns the input string centered in a field of length Len. If the input string without leading and trailing spaces is longer than Len, it is cut off at Len. In this case, Glb_Ok is set to false. Examples : Examples : Mystring:=' abc '; 1. Mystring:=Justify_Center(Mystring,5); This example returns Mystring = ' abc '. 2. Mystring:=Justify_Center(Mystring,1); The value returned is 'a' and Glb_Ok is false. Chapter III, Screen Control Language page 144 Chapter III, Screen Control Language page 144 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual System Functions System Functions FUNCTION Environment(Name:String128):String128; FUNCTION Environment(Name:String128):String128; This function returns the content of the specified line out of the DOS Environment. For Details on the DOS Environment and how it can be DOS Environment used refer to the description of the 'Set' command in your DOS manual. Example: Example: Var Mystr:String; BEGIN; Mystr:=Environment('COMSPEC'); END; Mystring contains now the complete path and name of your systems primary command processor, for example 'C:/COMMAND.COM'. PROCEDURE Execute(VAR Progstring:String80); VAR Result:INTEGER); PROCEDURE Execute(VAR Progstring:String80); VAR Result:INTEGER); This Procedure executes the program specified by 'Progstring'. Once this program has finished execution, control is returned to the calling program (your application). Since Execute does not read the settings of 'Path' or 'Environment', Execute 'Progstring' must contain, beside the actual program name, the complete path description if the program to be executed is not in the Active directory. In addition, 'Progstring' can optionally contain Active directory one or more parameters. The program name extension (i.e '.EXE' or '.COM' is optional. If no extension is specified, Execute will first Execute look for a '.COM' and then, in case it is not found for a '.EXE' file. The result of the operation are returned in DOSERROR and DOSEXTCODE (see your Turbo Pascal Manual). Example: Example: Execute('C:\Myprog firstparam secondparam thirdparam'); {Fires up 'Myprog' with three parameters. Once 'Myprog' has finished, control is passed back to your application. Note that no extension for 'Myprog' has been specified in the above example. If 'Execute' does not find an extension, it first tries '.COM' and if such a file cannot be found, it then tries '.EXE'} Note: See also the 'ExecuteDos' command. Note: Chapter III, Screen Control Language page 145 Chapter III, Screen Control Language page 145 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE ExecuteDos(Command:String128); PROCEDURE ExecuteDos(Command:String128); This procedure fires up the DOS command processor (usually COMMAND.COM) and passes the string contained in 'Command' to it. The command processor the acts upon this string in the same way as if it had been entered on the normal DOS prompt. Once the command has been executed, the command processor terminates and control is passed back to your application. The results of the operation are returned in DOSERROR and DOSEXITCODE (see turbo Pascal 4.0 Manual). If 'Command' is an empty string (i.e a string with a length of 0) or if it only contains blanks, the DOS Command processor is fired up and remains active for input until it is terminated with the DOS Command Exit (refer to your DOS Manual for details). Then control is passed Exit back to your program. Note: In addition to actual DOS commands there are also some other Note: programs which require COMMAND.COM to be running in order to execute properly. This applies particularly to many external commands (for example CHKDSK.COM) but also to all kind of batch file processing. Such tasks must therefore be started up using 'ExecuteDos' rather than 'Execute'. An important restriction for both 'Execute' and 'ExecuteDos' is the fact that they only work if the application program has been compiled to disk. In addition you must make sure that enough memory has been left over for the programs to be executed. In order to achieve this you must limit the Maximum free dynamic memory value (the 'A' Maximum free dynamic memory selection on TURBO PASCALS 'Option' menu) to an appropriate value prior to compiling your program. The value to choose cannot be exactly determined, it very much depends on your program. Crude guidelines can be found in Appendix A. Examples: Examples: ExecuteDos('Dir a:*.*') ExecuteDos('Dir a:*.*') {Loads the command processor and passes 'Dir a:*.*' to it. Once the 'Dir' command has been performed, the command processor terminates and control is passed back to your program.} ExecuteDos(''); ExecuteDos(''); {Invokes DOS including the familiar prompt. You can now enter any commands you want. 'Exit' returns you to your program. Note: For further examples of the above constructs refer to Appendix Note: A. Chapter III, Screen Control Language page 146 Chapter III, Screen Control Language page 146 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Date related routines Date related routines Most of the following routines apply the specifications being contained in the DOS Country Information for date formatting. This DOS Country Information offers the tremendous advantage that the appropriate routines in your program never have to be changed, independant of the country the program is used in. For more details on this matter please refer to the Appendix A. FUNCTION Date:String10; FUNCTION Date:String10; Returns the system date in form of a string. Both its format, i.e MMDDYY or DDMMYY, and the delimiters being used are obtained and automatically set according to the Country Information SCL has been Country Information SCL told to use. By default, SCL assumes the country specified in the SCL file 'CONFIG.SYS'. There are several possibilities to influence or override this selection within SCL, for details refer to Appendix A. SCL Assuming the Country is UK (Country = 44) 'Date' returns a string of the form 'DD-MM-YY', in the case of Germany (Country = 49) it would be 'DD.MM.YY' and for USA (Country = 1) the format would be 'MM-DD- YY'. FUNCTION Date_String(Y,M,D:WORD):String10; FUNCTION Date_String(Y,M,D:WORD):String10; This function returns the date passed to it as integers (Y,M and D) in form of a string. Everything having been said above for the function 'Date' applies to 'Date_String' as well. Date_String accepts the year in both 2 and 4 digit format. Chapter III, Screen Control Language page 147 Chapter III, Screen Control Language page 147 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE Check_Date(VAR Date_Str:String10; VAR Y,M,D:WORD); PROCEDURE Check_Date(VAR Date_Str:String10; VAR Y,M,D:WORD); 'Check_Date' converts 'Date_Str' into three integers values Y,M and D. 'Date_Str' must contain a valid date in the format DD-MM-YY or MM-DD-YY, depending on the Country Information being used (see Country Information above). The separators can be any non numerical characters. Leading zeroes can be omitted. The year can be entered either in full (as for example '1987') or as a 2 digit number (as '87'). The date in 'Date_Str' is checked for validity and, if it is found to be invalid, 'Glb_Ok' is set to false. FUNCTION Weekday(Y,M,D:WORD):INTEGER; FUNCTION Weekday(Y,M,D:WORD):INTEGER; 'Weekday' calculates the day of the week for the date passed to it in Y,M and D. The day of the week is returned in form of an Integer number. The meanings are: 0=Sunday, 1=Monday and so on. Please notice that if the year is passed to this function as a 2 digit value 1900 is added to it. Therefore this routine cannot be used for years below 100 A.D. FUNCTION Julian_Date(VAR Y,M,D:WORD):REAL; FUNCTION Julian_Date(VAR Y,M,D:WORD):REAL; This function returns the date passed to it in Y,M,D in form of a number of days since 1.Jan 00 A.D. The value passed back is in form of a REAL number. Julian_Date can be ideally used to calculate the number of days between two dates. If 'Y' contains a value less than 100, 1900 is added to it. Therefore this routine can not be used for any year below 100 A.D. PROCEDURE Normal_Date(VAR Julian:REAL;VAR Y,M,D:WORD); PROCEDURE Normal_Date(VAR Julian:REAL;VAR Y,M,D:WORD); Normal_Date is the counterpart of 'Julian_Date' above, i.e it converts a Julian date passed to it into three Integer Values Year, Month and Day. Note: For examples on how to use the above routines please refer to Note: Appendix A. Chapter III, Screen Control Language page 148 Chapter III, Screen Control Language page 148 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Time related Routines Time related Routines FUNCTION Time(Seconds:BOOLEAN):String10; FUNCTION Time(Seconds:BOOLEAN):String10; 'Time' returns the system time (24 hour based) in form of a string. If 'Seconds' is TRUE, this string has the format HH:MM:SS, otherwise it is HH:MM. The separators being used (in the above example ':') depends on the Country Information and can therefore be different Country Information depending on the country. Refer to Appendix A for details. FUNCTION Time_String(H,M,S:WORD):String10; FUNCTION Time_String(H,M,S:WORD):String10; 'Time_String' converts the time passed to it in H,M and S to a string of the form 'HH:MM:SS'. Leading blanks are replaced by '0'. Everything having been said under 'Time' regarding separators applies to this function as well. In order to obtain a time string without seconds the following construct may be used: Mystring:=COPY(Time_String(H,M,S),1,5); PROCEDURE Check_Time(VAR Time_Str:String10; VAR H,M,S : WORD); PROCEDURE Check_Time(VAR Time_Str:String10; VAR H,M,S : WORD); Converts the value in 'Time_Str' to three Integers and checks it for validity. If the check does not succeed, 'Glb_Ok' is set to false. The string passed in 'Time_Str' must have one of the following formats: 'HH:MM:SS' or 'HH:MM'. Leading zeroes can be omitted. Separators can be any non numerical characters. Hours are assumed to be based on the 24 hour format. Chapter III, Screen Control Language page 149 Chapter III, Screen Control Language page 149 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Background Processing Tasks Background Processing Tasks SCL is capable to perform user written routines as Background tasks. Background tasks There are two different hooks for Background Tasks provided in SCL, Background Tasks one for low priority and the other for high priority work. The High priority background task is unconditionally performed by SCL every time it goes through the internal loop of 'Handle_Format' (Whenever SCL waits for keyboard input it is idling in this loop). The low priority background task is identical except that it is only performed when no other tasks are pending, i.e. there is no keyboard input waiting to be processed and no screen updates are required. In order to declare a user written routine (Procedure) to be performed as a background task by SCL all you need is to include one of the following two statements in the program: LP_Background_Pointer:=@<Procedurename>; {this will cause SCL to execute <Procedurename> as a Low Priority background task} or HP_Background_Pointer:=@<Procedurename> {SCL will execute <Procedurename> as a High priority Background Task} Note: Please notice that background procedures must be compiled with Note: the 'Force Far Calls' Compiler Option. More details on Background tasks can be found in the explanation of SAMPLE4 distributed in Appendix A. Chapter III, Screen Control Language page 150 Chapter III, Screen Control Language page 150 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Other Routines Other Routines FUNCTION St(I:INTEGER):String80; FUNCTION St(I:INTEGER):String80; Returns an Integer number converted to a string. This function is especially useful to write numeric values to format fields. Example: Mystring:=St(15) returns '15' in Mystring. Example FUNCTION Rst(R:REAL;Decimals:INTEGER):String80; FUNCTION Rst(R:REAL;Decimals:INTEGER):String80; Returns an Real number converted to a string. Decimals must contain the number of positions to be shown after the decimal point. Example: Mystring:=Rst(3.55555,2) returns '3.56'. Example FUNCTION Nr(St:String80) : INTEGER; FUNCTION Nr(St:String80) : INTEGER; Converts a string into an Integer number. 'St' must be a string expressing an integer value. If 'St' does not epress an Integer value according to the rules for numeric constants then 'Nr' returns 0 (zero) and Glb_Ok is set to false. This function is mainly intended to read numeric format fields into integer variables. Example: My_Integer_Number :=Nr(G_Var(2)); Example FUNCTION Rnr(St:String80) : REAL; FUNCTION Rnr(St:String80) : REAL; Converts a string into an Real number. 'St' must be a string expressing a valid real value. If 'St' does not epress a Real value according to the rules for numeric constants then 'Rnr' returns 0 (zero) and Glb_Ok is set to false. This function is mainly intended to read the contents of numeric format fields into 'Real' variables. Example: My_Real_Number :=Rnr(G_Var(2)); Example Chapter III, Screen Control Language page 151 Chapter III, Screen Control Language page 151 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual FUNCTION Power(Mantissa, Exponent : REAL):REAL; FUNCTION Power(Mantissa, Exponent : REAL):REAL; Returns the value of Mantissa raised to the power of Exponent. FUNCTION Exist(Fn : String80):BOOLEAN; FUNCTION Exist(Fn : String80):BOOLEAN; Returns TRUE if a file with the name of Fn exists. Fn can contain a complete path description according to DOS rules. PROCEDURE Beep; PROCEDURE Beep; Creates a sound with a length of 'Beep_Time' clock ticks, alternating every every clock tick between the two frequencies 'Beep_Frequency_1' and 'Beep_Frequency_2'. Note: A clock tick occurs approximately 18.2 times per second (about Note: every 55 ms). FUNCTION Sys_Msg(Msgnr : INTEGER):String80; FUNCTION Sys_Msg(Msgnr : INTEGER):String80; Returns the text of record <Msgnr> in file <Screenfile>.ERR. Can be used in user programs to receive strings etc stored in this file (See also Appendix A; "The error message file"). FUNCTION Format_Name:String10; FUNCTION Format_Name:String10; Returns the name of the currently active format. Chapter III, Screen Control Language page 152 Chapter III, Screen Control Language page 152 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Chapter IV Chapter IV OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual This Page is intentionally left blank OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual S C L S C L Data Communications Subsystem Data Communications Subsystem OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Introduction Introduction Due to their background tasking capability, SCL programs are ideally suited for data communications. This opens many exciting possibilities especially in the area of micro-mainframe connections, but also allow you to build terminal emulators etc. The datacom routines provided by SCL allow you to easily develop complex protocols that enable SCL programs to communicate with other machines via the RS232 serial interface. All necessary communications parameters can be programatically changed and easily adapted to any requirements. The actual handling and monitoring of the RS232 port is interrupt driven and therefore very powerful without imposing unnecessary overhead on your program. The following discusses the complete SCL Data Communications Subsystem. In order to help you develop your own protocols two example programs have been provided on your distribution disks, these will be discussed as well. Note: Note: In order to utilize the SCL Data Communications routines, your computer must be equipped with a serial asynchronous Interface (COM1:). This Interface will typically be connected to a Modem. CHAPTER IV, SCL Data Communication subsystem page 156 CHAPTER IV, SCL Data Communication subsystem page 156 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Global Communications Parameters Global Communications Parameters The following parameters must be set according to your needs. Since all major parameters are declared using Typed Constants this Typed Constants can be done either in the program source or during runtime. DC_Parity DC_Parity Declaration: CONST Dc_Parity : CHAR = 'E'; This parameter determines which parity is being used, if any. The possible values are 'E' (Even), 'O' (Odd) and 'N' (None). DC_Stopbits. DC_Stopbits. Declaration: CONST Dc_Stopbits : Integer = 1; Set this value to 2 if two stopbits are required. DC_Speed DC_Speed Declaration: CONST Dc_Speed : Integer = 9600; This parameter determines the line speed in baud. The possible values are 110, 150, 300, 600, 1200, 2400, 4800 and 9600 baud. DC_Charsize DC_Charsize Declaration: CONST Dc_Charsize : Integer = 7; This value determines the number of bits per character. The possible values are 7 or 8. BCC_Set BCC_Set Declaration: CONST BCC_Set : BOOLEAN = FALSE; If this variable is TRUE, a Block Check Character is sent with all messages. Refer to the description of 'Send_Buffer' for further details. CHAPTER IV, SCL Data Communication subsystem page 157 CHAPTER IV, SCL Data Communication subsystem page 157 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Timers and Delays Timers and Delays Tx_Char_Timeout Tx_Char_Timeout Declaration: CONST Tx_Char_Timeout : INTEGER = 500; Maximum time to wait until the previous character has been sent in milliseconds. See also procedure 'DC_Write'. Rts_Cts_Timeout Rts_Cts_Timeout Declaration: CONST Rts_Cts_Timeout : INTEGER = 500; Maximum time in milliseconds to wait for 'Clear to Send' after 'Request to send' was raised. See also function 'Tx_Ok'. Rts_Cts_Delay Rts_Cts_Delay Declaration: CONST Rts_Cts_Delay : INTEGER = 0; Minimum time in milliseconds between the raising of 'Request to send' and sending of the first character. This option is required with some datasets where 'clear to send' may come up before the modem is actually ready to receive the first character. Rts_Holdover Rts_Holdover Declaration: CONST Rts_Holdover : INTEGER = 0; The time in milliseconds to wait before 'Request to send' is dropped after the last character has been transmitted. This option is required with some datasets in order to avoid datacom line noise. CHAPTER IV, SCL Data Communication subsystem page 158 CHAPTER IV, SCL Data Communication subsystem page 158 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Data Communications Control Characters Data Communications Control Characters The following definitions have been provided to enhance the readability and to facilitate the writing of terminal and line protocols. CONST Nul = $0; Soh = $1; Stx = $2; Etx = $3; Eot = $4; Enq = $5; Ack = $6; Bel = $7; Con = $7; Bs = $8; Ht = $9; Lf = $a; Vt = $b; Ff = $c; Cr = $d; S0 = $e; S1 = $f; Dle = $10; Dc1 = $11; Dc2 = $12; Dc3 = $13; Dc4 = $14; Nak = $15; Syn = $16; Etb = $17; Can = $18; Em = $19; Sub = $1a; Esc = $1b; Fs = $1c; Gs = $1d; Rs = $1e; Us = $1f; Pol = $70; Sel = $71; Fsl = $73; Bsl = $74; Del = $7f; CHAPTER IV, SCL Data Communication subsystem page 159 CHAPTER IV, SCL Data Communication subsystem page 159 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Other Declarations Other Declarations DC_Buff_Size DC_Buff_Size Declaration: CONST DC_Buff_Size = 2500; This is the size of the circular buffer in which the received characters are written by the interrupt service routine. DC_Rx_Buffer DC_Rx_Buffer Declaration: VAR DC_Rx_Buffer : ARRAY[0..DC_Buff_Size] of BYTE; The circular buffer used by the interrupt service routine. DC_Rx_Buff_Bottom DC_Rx_Buff_Bottom Declaration: CONST DC_Rx_Buff_Bottom : INTEGER = 0; Points to the 'bottom' (= the first character to be read) of DC_Rx_Buffer. If DC_Rx_Buff_Bottom is equal to DC_Rx_Buff_Top then the receive buffer is empty. DC_Rx_Buff_Top DC_Rx_Buff_Top Declaration: CONST DC_Rx_Buff_Top : INTEGER = 0; Points to the 'Top' (= the position where the ISR will write the next character received) of DC_Rx_Buffer. If DC_Rx_Buff_Bottom is equal to DC_Rx_Buff_Top then the receive buffer is empty. CHAPTER IV, SCL Data Communication subsystem page 160 CHAPTER IV, SCL Data Communication subsystem page 160 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Bcc Bcc Declaration: VAR Bcc : Byte; Used to calculate the block check character. DC_Open DC_Open Declaration: CONST Dc_Open : BOOLEAN = FALSE; This Typed Constant is set to TRUE if the SCL datacom system is Typed Constant initialized. CHAPTER IV, SCL Data Communication subsystem page 161 CHAPTER IV, SCL Data Communication subsystem page 161 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Data Communications SCL Data Communications Procedures and Functions Procedures and Functions CHAPTER IV, SCL Data Communication subsystem page 162 CHAPTER IV, SCL Data Communication subsystem page 162 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Initializing and Terminating DC Initializing and Terminating DC PROCEDURE Open_Dc(VAR Result:INTEGER); PROCEDURE Open_Dc(VAR Result:INTEGER); This procedure initializes the datacom subsystem and installs the Interrupt Service Routine to receive characters. All parameters like line speed, parity etc must be correctly set before this procedure is called. Both Line and Modem status after the initialization are returned in 'Result'. The meaning of 'Result' is as follows: Bit High order byte (line status) Low order Byte (Modem) Bit High order byte (line status) Low order Byte (Modem) 7 Time_Out Error Rx line signal detect 6 Transfer Shift Register empty Ring indicator 5 Transfer Holding Register empty Data set ready 4 Break_Detect error Clear to send 3 Framing error Delta RxLSD 2 Parity error Trailing edge RI 1 Overrun error Delta DSR 0 Data Ready Delta CTS PROCEDURE Close_Dc; PROCEDURE Close_Dc; This procedure must be called to terminate the DC subsystem. It deinstalls the interrupt service routine and reinstates the interrupt vector to its original content. Failing to call this routine before the program is finished can lead to strange effects and may make a system reboot necessary. CHAPTER IV, SCL Data Communication subsystem page 163 CHAPTER IV, SCL Data Communication subsystem page 163 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Sending Data Sending Data PROCEDURE Send_Char(Code:BYTE ; VAR OK:BOOLEAN); PROCEDURE Send_Char(Code:BYTE ; VAR OK:BOOLEAN); This procedure raises RTS, and, once CTS is raised, sends the character with the ASCII code of 'Code' onto the RS232 interface. Then RTS is dropped again. If either CTS does not come up within 'RTS_CTS_Timeout' or if the character cannot be sent within 'Tx_Char_Timeout' then the operation is aborted and 'Ok' is returned FALSE. Example: Example: Send_Char(EOT,Ok); {sends an 'EOT' character (ASCII 4) } PROCEDURE Send_String(Data:String255;VAR OK:BOOLEAN); PROCEDURE Send_String(Data:String255;VAR OK:BOOLEAN); This procedure is similar to 'Send_Char' except that a string (Data) is sent. Example: Example: Send_String('Hello',Ok); PROCEDURE Send_Buffer(VAR Tx_Buff; PROCEDURE Send_Buffer(VAR Tx_Buff; Buff_Start,Buff_Length,Bcc_Add:INTEGER; Buff_Start,Buff_Length,Bcc_Add:INTEGER; Head:String255; var Ok:BOOLEAN); Head:String255; var Ok:BOOLEAN); This procedure first sends the string 'Head', then an 'STX' character (ASCII 2) and thereafter 'Buff_Length' bytes of 'Tx_Buff', starting at a displacement of 'Buff_Start' bytes. Then an 'ETX' (ASCII 3) is sent. If 'BCC_Set' is true, a block check character follows. This block check character is calculated by adding all characters starting from the 'STX' up to and including the 'ETX' to Bcc_Add without Carry, i.e using an 'XOR' function. 'Bcc_add' can be used to include 'Head' into the Bcc calculation if required. Error handling etc are identical to the those described under 'Send_String'. The data contained in Tx_Buff must be bytes representing the ASCII codes of the characters to be sent. This procedure is compatible with the most commonly used data communication protocols. Note: Note: An example for 'Send_Buffer' is shown on the next page. CHAPTER IV, SCL Data Communication subsystem page 164 CHAPTER IV, SCL Data Communication subsystem page 164 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example: Example: PROCEDURE Example; VAR My_Buffer:ARRAY[0..2000] of bytes; My_Header:String255; Write_Ok :BOOLEAN; CONST My_String:String255 = 'Hello'; BEGIN; BCC_Set:=TRUE; {send block check character} My_Header:=SOH + 'A' + '1'; {a typical header for poll/select} MOVE(My_String,My_Buffer,LENGTH(My_String)+1); {first byte is length of the Send_Buffer(My_Buffer,1,LENGTH(My_String),0,My_Header,Write_Ok); END; {displacement of 1 to exclude the byte containing length} The above procedure causes the following string to be sent: <SOH>A1<STX>Hello<ETX><BCC> The BCC is calculated without header (starting from 'STX'). If it is required to include the header into the BCC calculation, its BCC must be calculated externally and passed to 'Send_Buffer' via 'BCC_Add'. For this example the BCC for the header could be calculated using the following statement: Head_Bcc := SOH XOR ORD('A') XOR ORDd('1'); CHAPTER IV, SCL Data Communication subsystem page 165 CHAPTER IV, SCL Data Communication subsystem page 165 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Receiving Data Receiving Data PROCEDURE Receive_Char(VAR Code:INTEGER; VAR Ok:BOOLEAN); PROCEDURE Receive_Char(VAR Code:INTEGER; VAR Ok:BOOLEAN); Returns the ASCII Code of the character in the circular receive buffer pointed to by the 'Bottom' pointer (This character was received from datacom and put into the buffer by the Interrupt Service Routine). The 'Bottom' buffer pointer is then incremented. If the circular receive buffer does not contain any characters (Top = Bottom) then 'Ok' is returned FALSE. CHAPTER IV, SCL Data Communication subsystem page 166 CHAPTER IV, SCL Data Communication subsystem page 166 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Other Functions Other Functions PROCEDURE Disable_Port; PROCEDURE Disable_Port; This Procedure can be called to disable the RS232 port temporarily, for example to change parameters. PROCEDURE Enable_Port; PROCEDURE Enable_Port This procedure reinstates datacom if it was disabled using 'Disable_Port'. PROCEDURE Clear_Rx_Buffer; PROCEDURE Clear_Rx_Buffer; This Procedure clears the circular receive buffer, i.e it sets Top equal to Bottom. PROCEDURE Set_DC_Params; PROCEDURE Set_DC_Params; This Procedure must be called if data communication parameters (speed, parity etc) have been changed. The following sequence of procedures is recommended to change communication parameters: Disable_Port; DC_Speed:=4800; Set_DC_Params; Enable_Port; Clear_RX_Buffer; PROCEDURE DC_Diagnose(On:BOOLEAN); PROCEDURE DC_Diagnose(On:BOOLEAN); If 'On' is TRUE, the loopback feature for diagnostic testing will be set. This causes the output of the 'Send' shift register in the RS232 adapter to be directly looped back to the 'Receive' shift register input, i.e all data transmitted is immediately received again. If 'On is FALSEl the loopback feature will be reset and normal operation is resumed. This feature can be used for test purposes. PROCEDURE Get_Dc_Status(VAR Status:INTEGER); PROCEDURE Get_Dc_Status(VAR Status:INTEGER); This procedure returns the present line and modem status. The meaning of 'Status' is the same as described under 'Open_Dc'. CHAPTER IV, SCL Data Communication subsystem page 167 CHAPTER IV, SCL Data Communication subsystem page 167 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Low Level Routines Low Level Routines PROCEDURE Set_Dtr(On:BOOLEAN); PROCEDURE Set_Dtr(On:BOOLEAN); Depending on the the status of 'On', this procedure sets or resets Data terminal Ready. If 'On' is FALSE, Request to send will also be dropped. PROCEDURE Set_Rts(On:BOOLEAN); PROCEDURE Set_Rts(On:BOOLEAN); This procedure raises or drops Request to send. PROCEDURE DC_Write(Code:BYTE;VAR Ok:BOOLEAN); PROCEDURE DC_Write(Code:BYTE;VAR Ok:BOOLEAN); This procedure sends the character indicated by 'Code' onto the RS232 Interface. It does not manipulate RTS as the appropriate High Level Routines do (Send_...). The setting and resetting of RTS can be performed with 'Tx_Ok' and 'Set_Rts'. If the Character cannot be sent before 'Tx_Char_Timeout' the operation is aborted and 'Ok' is returned FALSE. FUNCTION Tx_Ok:BOOLEAN; FUNCTION Tx_Ok:BOOLEAN; Tx_Ok raises 'Request to send' and returns TRUE if Clear to Send comes up before 'Rts_Cts_Timeout'. FUNCTION Dsr:BOOLEAN; FUNCTION Dsr:BOOLEAN; Dsr returns the present status of Data set ready. FUNCTION Cts:BOOLEAN; FUNCTION Cts:BOOLEAN; Cts returns the present status of Clear to send. PROCEDURE DC_Break; PROCEDURE DC_Break; This procedure causes a 'Break' to be sent. CHAPTER IV, SCL Data Communication subsystem page 168 CHAPTER IV, SCL Data Communication subsystem page 168 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE DC_Isr; PROCEDURE DC_Isr; This is the Interrupt service routine for interrupt Hex 0C. It is called by the IRQ4 whenever a character has been received via the RS232 Interface. DC_Isr fetches this character and places it into the circular Receive buffer where it the can be read using 'Receive_Char'. DC_Isr may not be called directly by a user program. CHAPTER IV, SCL Data Communication subsystem page 169 CHAPTER IV, SCL Data Communication subsystem page 169 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Data communications SCL Data communications Example Programs Example Programs Chapter IV, SCL Data Communication example programs page 170 Chapter IV, SCL Data Communication example programs page 170 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual A Simple Line Monitor (SAMPLE7.PAS) A Simple Line Monitor (SAMPLE7.PAS) In this example program the SCL datacom routines are used to build a simple datacom line monitor which interprets and displays and interprets the traffic on a datacom line. The major datacom parameters like baudrate, wordsize, number of stopbits and parity can be dynamically changed while the interpretation of the line traffic is instantly visible. This program is therefore a neat tool to rapidly decipher the parameter settings of the datacom line you are connected to. In order to verify the functionality of this program, just connect COM1: to a busy datacom line and start it. Below you find the complete source code of the line monitor program, a detailed description follows afterwards. Chapter IV, SCL Data Communication example programs page 171 Chapter IV, SCL Data Communication example programs page 171 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Listing of SAMPLE7.PAS Listing of SAMPLE7.PAS PROGRAM dc_monitor; {a simple datacom line monitor} uses scl; {make SCL accessible} VAR Ok : BOOLEAN; Wrkstr : String80; Temp : INTEGER; Freeze : BOOLEAN; FUNCTION Xlate(Cn:INTEGER):String10; {datacom control character} VAR Tmp:String10; {interpretation} BEGIN; CASE Cn OF $0 : Tmp:='<NUL>'; $1 : Tmp:='<SOH>'; $2 : Tmp:='<STX>'; $3 : Tmp:='<ETX>'; $4 : Tmp:='<EOT>'; $5 : Tmp:='<ENQ>'; $6 : Tmp:='<ACK>'; $7 : Tmp:='<BEL>'; $8 : Tmp:='<BS>'; $9 : Tmp:='<HT>'; $a : Tmp:='<LF>'; $b : Tmp:='<VT>'; $c : Tmp:='<FF>'; $d : Tmp:='<CR>'; $e : Tmp:='<S0>'; $f : Tmp:='<S1>'; $10: Tmp:='<DLE>'; $11: Tmp:='<DC1>'; $12: Tmp:='<DC2>'; $13: Tmp:='<DC3>'; $14: Tmp:='<DC4>'; $15: Tmp:='<NAK>'; $16: Tmp:='<SYN>'; $17: Tmp:='<ETB>'; $18: Tmp:='<CAN>'; $19: Tmp:='<EM>'; $1a: Tmp:='<SUB>'; $1b: Tmp:='<ESC>'; $1c: Tmp:='<FS>'; $1d: Tmp:='<GS>'; $1e: Tmp:='<RS>'; Chapter IV, SCL Data Communication example programs page 172 Chapter IV, SCL Data Communication example programs page 172 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual $1f: Tmp:='<US>'; $70: Tmp:='<POL>'; $71: Tmp:='<SEL>'; $72: Tmp:='<FSL>'; $73: Tmp:='<BSL>'; $7f: Tmp:='<DEL>'; $80..$ff: Tmp:='<' + St(Cn) + '>'; {return character code} ELSE Tmp:=CHR(Cn); {return character} END; Xlate:=Tmp; END; {$F+} {far call option required for SCL background tasks} PROCEDURE Lp_Background_Task; {updates the line traffic field} BEGIN; IF NOT Freeze THEN {F9 toggles Freeze} BEGIN; REPEAT Receive_Char(Temp,Ok); {receive char from datacom} IF Ok THEN {there was one} BEGIN; Wrkstr:=Wrkstr+Xlate(Temp); {interpret it} WHILE LENGTH(Wrkstr) > 76 DO {cut off oldest} DELETE(Wrkstr,1,1); END; UNTIL NOT Ok; {no more characters} W_Cont(7,Wrkstr); {update traffic field} END; END; {$F-} {reset far calls again} Chapter IV, SCL Data Communication example programs page 173 Chapter IV, SCL Data Communication example programs page 173 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE Update_Params; {spacebar pressed} VAR Sp:INTEGER; BEGIN; CASE Active_Field OF 1: BEGIN; {linespeed} Sp:=Nr(G_Cont(1)); {get current speed} IF Sp = 110 THEN Sp:= 150 ELSE IF Sp = 150 THEN Sp:= 300 ELSE {switch} IF Sp = 300 THEN Sp:= 600 ELSE {to} IF Sp = 600 THEN Sp:=1200 ELSE {next} IF Sp = 1200 THEN Sp:=2400 ELSE {speed} IF Sp = 2400 THEN Sp:=4800 ELSE IF Sp = 4800 THEN Sp:=9600 ELSE Sp:=110; Dc_Speed:=Sp; {update speed} W_Cont(1,St(Sp)); {update field} END; 2: BEGIN; {char size} Sp:=Nr(G_Cont(2)); Sp:=Sp+1; IF Sp > 8 THEN Sp:=5; Dc_Charsize:=Sp; {update param} W_Cont(2,St(Sp)); {update field} END; 3: BEGIN; Sp:=Nr(G_Cont(3)); {stop bits} IF Sp = 1 THEN Sp:=2 ELSE Sp:=1; Dc_Stopbits:=Sp; {update param} W_Cont(3,St(Sp)); {update field} END; 4: IF G_Cont(4) = 'Even'THEN {parity} BEGIN; W_Cont(4,'None'); Dc_Parity:='N'; END ELSE IF G_Cont(4) = 'None'THEN BEGIN; W_Cont(4,'Odd'); Dc_Parity:='O'; END ELSE BEGIN; W_Cont(4,'Even'); Dc_Parity:='E'; END; END; Chapter IV, SCL Data Communication example programs page 174 Chapter IV, SCL Data Communication example programs page 174 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Disable_Port; {temporary disable datacom} Set_Dc_Params; {set new dc params} Enable_Port; {enable datacom again} END; PROCEDURE Handle_Uf; BEGIN; IF Char_Code = 32 THEN {Spacebar pressed} BEGIN; Update_Params; {update dc params} Char_Code:=Code_Noop; {no further action} END ELSE IF Char_Code = Code_F9 THEN {F9 Pressed} BEGIN; Freeze:= NOT Freeze; {toggle freeze} Char_Code:=Code_Noop; {no further action} END ELSE IF Char_Code = Code_Return THEN Char_Code:=Code_Tab ELSE IF Char_Code = Code_Escape THEN Char_Code:=Code_Noop; END; PROCEDURE Handle_First; {This Procedure handles format 'first'.} BEGIN; Select_Format('main'); W_Cont(1,St(Dc_Speed)); {prefill} W_Cont(2,St(Dc_Charsize)); {the} W_Cont(3,St(Dc_Stopbits)); {fields} IF Dc_Parity = 'E' THEN W_Cont(4,'Even') ELSE IF Dc_Parity = 'O' THEN W_Cont(4,'Odd') ELSE W_Cont(4,'None'); Freeze:=FALSE; {display incoming traffic} Display_Format(0,0); REPEAT Handle_Format; {Complete Loop to handle format input} IF User_Function THEN {user key pressed} Handle_Uf; {user interrupt procedure} UNTIL Format_Done; {Either completely filled in or abort pressed} END; Chapter IV, SCL Data Communication example programs page 175 Chapter IV, SCL Data Communication example programs page 175 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual VAR Res:INTEGER; BEGIN; {of main} Wrkstr:=''; Select_Format_File('Sample7'); {initializes SCL and loads the format file 'Sample7'} LP_Background_pointer:=@LP_Background_task; {invoke our screen updating routine as low priority background task} Auto_Help_Set:=FALSE; {reset autohelp feature} Open_Dc(Res); {initialize Datacom system} Handle_First; {load,display and handle the format} Close_Formats; {terminate SCL} Close_Dc; {close Datacom system} END. {of main} Chapter IV, SCL Data Communication example programs page 176 Chapter IV, SCL Data Communication example programs page 176 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Description of SAMPLE7.PAS Description of SAMPLE7.PAS Main Program Main Program The first SCL datacom routine being called is 'Open_DC'. It initializes the datacom system and installs the Interrupt Service Interrupt Service Routine which from this very moment will receive all characters on Routine the datacom line and place them into the circular receive buffer. Then the procedure 'Handle_Main' is called to display and handle the only screen format in this program. If 'Handle_Main' is finished, 'Close_DC' is called which terminates the datacom system and deinstalls the ISR. Finally, 'Close_formats' terminates SCL as usual. Handle_Main Handle_Main As soon as the format is selected, its fields are 'prefilled' with the current settings of the main datacom parameters. The format is then displayed. The datacom line traffic is interpreted and displayed by the procedure LP_Background_Task. Handle_Uf Handle_Uf 'Handle_Uf is a user function procedure acting on several keyboard keys (Spacebar, F9, Return and Escape). In this program, the spacebar is used to change datacom parameters. If it is pressed, the procedure 'Update_Params' is called to process these changes. If F9 is pressed, the boolean variable 'Freeze' is toggled. If 'Freeze' is TRUE, the display of datacom line traffic is halted for better readability. Pressing F9 again will restart it. If Return is pressed, it is replaced by a 'Tab' to prevent SCL from terminating the format. 'Escape' is replaced by a NoOp (this program is terminated by pressing the 'Abort' key (F10). Update_Params Update_Params This procedure is called whenever the spacebar is pressed. For the currently active field, it substitutes the present SCL datacom parameter by the next possible choice and displays its new value. The datacom port is then temporarily disabled ('Disable_Port') before 'Set_DC_Params' is called to activate the new parameter setting. Finally the datacom port is enabled again using 'Enable_Port'. Chapter IV, SCL Data Communication example programs page 177 Chapter IV, SCL Data Communication example programs page 177 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual LP_Background_Task LP_Background_Task As long as 'Freeze' is FALSE, this 'Background processing' procedure permanently updates the line traffic display field (field 7). It reads all characters having been received since the last update from the circular buffer (using 'Receive_Char'). Each character is interpreted via the function 'Xlate' (see below) and the resulting string is then displayed in field 7. If the string to be outputed outgrows the size of the display window, the oldest characters are trimmed, thereby creating a horizontal scroll effect. For further informations on background processing please refer to Appendix A. Xlate Xlate This procedure makes the line traffic more readable by translating all ASCII codes representing datacom control characters into more meaningful strings. For example, character ASCII #4 is translated into the string '<EOT>'. Similarly, all codes above ASCII 125 are translated into strings showing their ASCII code in '< >' brackets (example: ASCII 130 is returned as '<130>'). For all other codes their corresponding character images are returned. Chapter IV, SCL Data Communication example programs page 178 Chapter IV, SCL Data Communication example programs page 178 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual A Terminal Emulator Program (SAMPLE 8) A Terminal Emulator Program (SAMPLE 8) This example program features a terminal emulator program using a rather complex poll select protocol, which is even capable of handling multiple receive/transmit buffers. It has been derived from a 'real world' SCL program which works on a BURROUGHS mainframe datacom network together with other terminals in a multipoint environment at 9600 baud and emulates the datacom protocol of a BURROUGHS TD830 Terminal. This example program is intended to demonstrate how to write a datacom protocol, for this reason the screen interface deliberately is basic and only consists of a single format with two fields, one where a message to be sent can be entered and another one were all messages received from the mainframe are displayed. Since nearly every mainframe type uses a different protocol, details specific to this protocol are purposely not covered in depth, the intention is to concentrate on the more common aspects of how to write terminal protocols with the help of SCL. Nevertheless this example can probably serve as a good basis for your own developments. Note: Note: There are many different possibilities to interface SCL programs to mainframes; typically an SCL program will emulate the datacom interface of a terminal and do all other internal tasks using its own resources, thus presenting the user with its own powerful capabilities. Dialogues with the mainframe are usually performed in the background, automatically and totally transparent to the user. Chapter IV, SCL Data Communication example programs page 179 Chapter IV, SCL Data Communication example programs page 179 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Listing of Example Program 8 Listing of Example Program 8 The following is an extract of SAMPLE8.PAS and shows the poll select handling routines used by this program. CONST Tx_Buffers = 1; {nr of xmit buffers; minimum = 1} Rx_Buffers = 1; {nr of receive buffers; minimum = 1} Dc_Addr_1 : Byte = $33; {first byte of terminal address} Dc_Addr_2 : Byte = $31; {second byte of terminal address} TYPE Buffer_Data = ARRAY[1..Dc_Buffer_Size] OF Byte; Buffer_Type = RECORD {description of rx and tx buffers} Len :INTEGER; {length of data in buffer} Data:Buffer_Data; END; Rx_Buffer_Type= ARRAY[0..Rx_Buffers] OF Buffer_Type; Tx_Buffer_Type= ARRAY[0..Tx_Buffers] OF Buffer_Type; VAR Rx_Buffer_Overflow:BOOLEAN; {rx data > buffersize} Rx_Buffer:Rx_Buffer_Type; Tx_Buffer:Tx_Buffer_Type; Result_Ok:BOOLEAN; Ch_Code:INTEGER; State:INTEGER; {used in poll select state machine} Rx_Buff_Wptr, {rx buffer to be filled next} Rx_Buff_Rptr, {rx buffer to be read next} Tx_Buff_Wptr, {tx buffer to be sent last} Tx_Buff_Rptr : INTEGER; {tx buffer to be sent first} This_Char_Done:BOOLEAN; {used in poll select state machine} Dc_Msg_Header:String255; Cont_String:String255; Char_Ind:INTEGER; Ok : BOOLEAN; Head_Bcc:INTEGER; PROCEDURE Ps_Handler; {poll select state machine. run as } BEGIN; {background task} IF This_Char_Done THEN {previous character finished} Receive_Char(Ch_Code,Ok); {get next char from dc rx buffer} IF Ok THEN {there was a character} Chapter IV, SCL Data Communication example programs page 180 Chapter IV, SCL Data Communication example programs page 180 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual BEGIN; This_Char_Done:=TRUE; {preset} CASE State OF 0:IF Ch_Code = Eot THEN State:=1; {eot received} 1:IF Ch_Code = Dc_Addr_1 THEN {first byte of address} State:=2 {wait for second byte} ELSE State:=0; {reset state machine} 2:IF Ch_Code = Dc_Addr_2 THEN {second byte of address} State:=3 {wait for cntrl char} ELSE State:=0; {reset state machine} 3:IF Ch_Code = Pol THEN State:=4 ELSE {poll string} IF Ch_Code = Sel THEN State:=7 ELSE {select string} IF Ch_Code = Fsl THEN State:=15 ELSE {fast sel} State:=0; {otherwise reset state machine} 4:IF Ch_Code = Enq THEN {end of string} BEGIN; This_Char_Done:=FALSE; {dont read next char} State:=5 {next is state = 5} END ELSE State:=0; {reset state machine} 5:IF Tx_Buffer[Tx_Buff_Rptr].Len = 0 THEN BEGIN; {no data to send} Send_Char(Eot,Ok); {send eot} State:=0; {..and reset state machine} END ELSE {there is data to be sent} BEGIN; {send it with header and bcc} Send_Buffer(Tx_Buffer[Tx_Buff_Rptr].Data, 1,Tx_Buffer[Tx_Buff_Rptr].Len,Head_Bcc, Dc_Msg_Header,Ok); IF Ok THEN {successfully sent} State:=6 {wait for ack} ELSE State:=0; {otherwise reset state machine} END; 6:BEGIN; IF Ch_Code = Ack THEN {ack received} BEGIN; Send_Char(Eot,Ok); {send eot} IF Ok THEN {successfully sent} BEGIN; {clear buffer & increase pointer} Tx_Buffer[Tx_Buff_Rptr].Len:=0; Tx_Buff_Rptr:=SUCC(Tx_Buff_Rptr) MOD Tx_Buffers; END; State:=0; {reset state machine} END Chapter IV, SCL Data Communication example programs page 181 Chapter IV, SCL Data Communication example programs page 181 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual ELSE IF Ch_Code = Nak THEN {mainframe didnt receive ok} BEGIN; {resend data} This_Char_Done:=FALSE; State:=5; END ELSE {mainframe did not respond} State:=0; {reset state machine} END; 7: IF Ch_Code = Enq THEN {end of sel string} BEGIN; This_Char_Done:=FALSE; {dont receive next char} State:=8; {answer} END ELSE State:=0; {reset state machine} 8: IF Rx_Buffer[Rx_Buff_Wptr].Len > 0 THEN BEGIN; {we have no rx buffer available} Send_Char(Nak,Ok); {send nak} State:=0; {reset state machine} END ELSE {we can receive data} BEGIN; Send_Char(Ack,Ok); {send ack} IF Ok THEN State:=9 ELSE {ack could be sent} State:=0; {otherwise reset state machine} END; 9: IF Ch_Code = Soh THEN State:=10 {SOH received} ELSE State:=0; 10: IF Ch_Code = Dc_Addr_1 THEN {first byte of address} State:=11 ELSE State:=0; 11: IF Ch_Code = Dc_Addr_2 THEN State:=12 {second byte of address received} ELSE State:=0; 12: BEGIN; IF Ch_Code = Stx THEN {stx received} BEGIN; Bcc:=Stx XOr Head_Bcc; {start bcc calculation} Char_Ind:=1; {init rx buffer} State:=13; {rx data} END ELSE State:=0; {reset state machine} END; Chapter IV, SCL Data Communication example programs page 182 Chapter IV, SCL Data Communication example programs page 182 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual 13: BEGIN; {receive data & write into rx buffer} IF (Char_Ind < Dc_Buffer_Size) AND (Ch_Code <> Etx) THEN BEGIN; {buffer not full and not etx received} Rx_Buffer[Rx_Buff_Wptr].Data[Char_Ind]:=Ch_Code; Bcc:=Bcc XOr Ch_Code; {bcc calculation} Char_Ind:=SUCC(Char_Ind); {increase buffer index} END ELSE IF Ch_Code = Etx THEN {etx received} BEGIN; Bcc:=Bcc XOr Etx; {get final bcc} Rx_Buffer[Rx_Buff_Wptr].Len:=Char_Ind - 1; State:=14; END ELSE {rx buffer overflow} BEGIN; State:=0; {reset state machine} Rx_Buffer_Overflow:=TRUE; {set flag} END; END; 14: BEGIN; IF Ch_Code = Bcc THEN {received = calculated bcc} BEGIN; Send_Char(Ack,Ok); {send an ACK} IF Ok THEN {successfully sent, next rx buffer} Rx_Buff_Wptr:=SUCC(Rx_Buff_Wptr) MOD Rx_Buffers ELSE Rx_Buffer[Rx_Buff_Wptr].Len:=0;{forget rx data} END ELSE {bcc error} BEGIN; Rx_Buffer[Rx_Buff_Wptr].Len:=0;{forget rx data} Send_Char(Nak,Ok); {send nak} END; State:=0; {reset state machine} END; 15: IF Ch_Code = Soh THEN State:=16 ELSE State:=0; {FSL} 16: IF Ch_Code = Dc_Addr_1 THEN State:=17 ELSE State:=0; 17: IF Ch_Code = Dc_Addr_2 THEN State:=18 ELSE State:=0; Chapter IV, SCL Data Communication example programs page 183 Chapter IV, SCL Data Communication example programs page 183 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual 18: BEGIN; IF Ch_Code = Stx THEN {stx received} BEGIN; IF Rx_Buffer[Rx_Buff_Wptr].Len > 0 THEN State:=0 {no rx buffer available} ELSE BEGIN; {start bcc calculation} Bcc:=Stx XOr Head_Bcc; Char_Ind:=1; {init buff index} State:=13; {wait for rx data} END; END ELSE State:=0; {reset state machine} END; ELSE State:=0; {reset state machine} END; {end case} IF Ch_Code = Eot THEN State:=1; {preset state machine} END; END; PROCEDURE Clear_Rx_Buffers; {clear all rx buffers} VAR X:INTEGER; BEGIN; FOR X:=0 TO Rx_Buffers DO Rx_Buffer[X].Len:=0; {set length to 0} Rx_Buff_Wptr:=0; {both pointers to 0} Rx_Buff_Rptr:=0; END; PROCEDURE Clear_Tx_Buffers; {clear all xmit buffers} VAR X:INTEGER; BEGIN; FOR X:=0 TO Tx_Buffers DO Tx_Buffer[X].Len:=0; {set length to 0} Tx_Buff_Wptr:=0; {set both pointers to 0} Tx_Buff_Rptr:=0; END; Chapter IV, SCL Data Communication example programs page 184 Chapter IV, SCL Data Communication example programs page 184 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE Init_Ps; {init poll select system} VAR Stat:INTEGER; BEGIN; Rx_Buffer_Overflow:=FALSE; Cont_String:=CHR(Dc_Addr_1) + CHR(Dc_Addr_2) + CHR(Pol) + CHR(Enq); {set up contention string} Dc_Msg_Header:=CHR(Soh)+CHR(Dc_Addr_1)+CHR(Dc_Addr_2); {header} Head_Bcc:=Dc_Addr_1 XOr Dc_Addr_2; {calculate bcc for header} State:=0; {reset state machine} Clear_Rx_Buffers; {clear rx buffers} Clear_Tx_Buffers; {clear tx buffers} This_Char_Done:=TRUE; Open_Dc(Stat); {open datacom & install ISR} Send_String(Cont_String,Result_Ok); {send contention string} END; FUNCTION Data_Received:BOOLEAN; {returns true if at least one } BEGIN; {of the rx buffers contains data} Data_Received:= Rx_Buffer[Rx_Buff_Rptr].Len > 0; END; FUNCTION Dc_Write_Ok:BOOLEAN; {returns true if at least one} BEGIN; {of the tx buffers is available} Dc_Write_Ok:=Tx_Buffer[Tx_Buff_Wptr].Len = 0; END; PROCEDURE Read_Dc(VAR Data;VAR Len:INTEGER;VAR Ok:BOOLEAN); BEGIN; {call this routine to obtain data received from Mainframe} IF Data_Received THEN {one of the rx buffers contains data} BEGIN; {return it} Len:=Rx_Buffer[Rx_Buff_Rptr].Len; Move(Rx_Buffer[Rx_Buff_Rptr].Data,Data,Len); Rx_Buffer[Rx_Buff_Rptr].Len:=0; {clear this buffer} Rx_Buff_Rptr:=SUCC(Rx_Buff_Rptr) MOD Rx_Buffers; {incr pointer} Ok:=TRUE; END ELSE Ok:=FALSE; {no rx data available} END; Chapter IV, SCL Data Communication example programs page 185 Chapter IV, SCL Data Communication example programs page 185 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual PROCEDURE Write_Dc(VAR Buff; Len:INTEGER;VAR Ok:BOOLEAN); BEGIN; {call this routine to send data to mainframe} IF Dc_Write_Ok THEN {tx buffer available} BEGIN; Move(Buff,Tx_Buffer[Tx_Buff_Wptr].Data,SIZEOF(Buff)); Tx_Buffer[Tx_Buff_Wptr].Len:=Len; Tx_Buff_Wptr:=SUCC(Tx_Buff_Wptr) MOD Tx_Buffers; Ok:=TRUE; END ELSE Ok:=FALSE; {no tx buffer available} END; Chapter IV, SCL Data Communication example programs page 186 Chapter IV, SCL Data Communication example programs page 186 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Description of SAMPLE8.PAS Description of SAMPLE8.PAS The following is a broad discussion of the datacom routines used in example program 8 including some useful hints on how to implement such datacom protocols in a SCL program. Poll-Select Terminal Protocol Handling System Poll-Select Terminal Protocol Handling System The main routines in this system are 'Write_DC', 'Read_DC' and 'PS_Handler'. 'Write_DC' does not actually write to the datacom line (this is done by the underlying SCL Datacom system under the control of 'PS_Handler'). It just places the message to be sent into the first available transmit buffer. If no empty buffer is available (i.e queue full) an error code is returned to the calling procedure within the user program. 'Read_DC' works in a similar fashion, it just returns the message waiting in the first read buffer. If there are no messages pending, an error code is returned. 'PS_Handler' forms the interface to the underlying SCL Datacom system. It runs as a background job (called from within 'HP_Background_Task'). 'PS_Handler' checks all incoming datacom traffic for messages addressed to this terminal and acts upon them as required. It mimics a typical 'State Machine' in form of a big case statement and is controlled by the variable 'State'. Whenever the mainframe polls the terminal, 'PS_Handler' checks whether there is a message in the write buffer. If there is none, it sends an 'EOT', otherwise it sends the message, preceeded with a header containing the terminal address and followed by ETX and a block check character. If the mainframe prompts this message with an ACK the buffer is discarded and the pointer increased to the next buffer to be sent. In case the mainframe sends a message, 'PS_Handler' removes the header and the control characters and stores it in the first available receive buffer where it then can be fetched by 'Read_DC'. This way of implementing a datacom protocol in a SCL program takes full advantage of SCL's background processing capabilities and allows a user program to treat complex datacom transactions very much like writing and reading to an ordinary file, without having to bother about any protocol conventions and underlying logic etc. On the following page you find a detailed description of the flow of data through the different layers of this datacom system. Chapter IV, SCL Data Communication example programs page 187 Chapter IV, SCL Data Communication example programs page 187 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Poll Select Handler Datacom read data flow Poll Select Handler Datacom read data flow ____________________________________________ 1 The RS232 adapter hardware receives the datacom message from the mainframe and, whenever a complete character has been received, raises a hardware interrupt. 2. This hardware interrupt invokes SCL's Interrupt Service Routine Interrupt Service Routine (DC_ISR) which fetches this character and places it into the circular receive buffer. 3. 'PS_Handler', called from within 'HP_Background_Task' checks whether one or more characters have been received since the last time it was executing and, if this is the case, calls 'Receive_Char' to read them, one at a time, from the circular receive buffer. It then determines the necessary action depending on the value of 'State'. In case the character is not intended for this terminal it is discarded, otherwise, if it is the last character of a control string, 'PS_Handler' sends a prompt to the mainframe, and finally, if it belongs to a message just being received it is placed into the first available receive buffer. Once all characters of this message have been received and placed into the receive buffer, this buffer is marked valid and now available to be read by 'Read_DC'. 4. 'Read_DC', called from within the user program, moves the complete message from the receive buffer into the selected user variable. Chapter IV, SCL Data Communication example programs page 188 Chapter IV, SCL Data Communication example programs page 188 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Poll Select Handler Datacom write data flow Poll Select Handler Datacom write data flow _____________________________________________ 1. Called from within the user program, 'Write_Dc' moves the message to be sent to the first available write buffer. 2. If 'PS_Handler' receives a Pollstring it checks whether one of the write buffers contains data to be sent and if this is the case, passes it, together with a header, on to the procedure 'Send_Buffer'. 3. Send_Buffer then calls 'DC_Write' to send it, character by character, out to the datacom line. 4. 'PS_Handler' then waits for an 'ACK' from the mainframe and subsequently discards the content of the write buffer. Chapter IV, SCL Data Communication example programs page 189 Chapter IV, SCL Data Communication example programs page 189 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Appendix A Appendix A Sample Program Discussion Sample Program Discussion OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Introduction Introduction In this section you be given some insight of the programming mechanisms used in the 5 small demo programs made available to you. Key SCL programming technic are demonstrated and discussed here. You will be able to make ample use of these programs for training purposes, we actually recommend that you study them thoroughly. Having OASIS installed in your system and being already somewhat familiar with its operation (It's dead easy, very intuitive indeed) you will then be in a position to examine the specifications of the formats used in these sample programs. For each program, under the header 'What you could try:' you will 'What you could try:' find some ideas and recommendations to familiarize yourself with SCL and to understand the features & constructs used in the program under review. By following these recommendations, you will soon realize how simple and effective the use of SCL can be. In the mean time you can appreciate the purity of code, the speed and the flexibility provided by OASIS SCL designed programs. Below is a brief overview of all sample programs described herewith. SAMPLE1 SAMPLE1 A very short program including a single format. This program is of no practical use and is mainly intended to exhibit the basic architecture and requirements of any SCL program. SAMPLE2 SAMPLE2 A simple program to print mailing labels on your printer. SAMPLE3 SAMPLE3 A program demonstrating how the SCL format stack works. In this example, up to 10 formats are displayed on the screen simultaneously, overlapping each other. SAMPLE4 SAMPLE4 An automatic Disk menu program. Any program can be executed directly from the menu just by pointing to it. It can also let you wander across all subdirectories on your disk. SAMPLE5 SAMPLE5 A little Demo Program giving an overview on some of the features of SCL. Run it ! Appendix A, sample programs discussion page 191 Appendix A, sample programs discussion page 191 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example 1 (OASIS Easy Fields) Example 1 (OASIS Easy Fields) ______________________________ Due to its simplicity, the first example program offers little practical use, but beside showing the very basic structure and the minimum requirements of any SCL program it is perfectly suited for your first acquaintance with OASIS. It consists of the following files: SAMPLE1.SCS : The format file, containing a single format. SAMPLE1.SCI : The index file to above. SAMPLE1.MSG : Contains all Field Messages. Field Messages SAMPLE1.PAS : The Turbo Pascal source program as listed below. SAMPLE1.EXE : Compiled version of SAMPLE1.PAS. Below is a complete listing of SAMPLE1.PAS. It is meant to give you some basic knowledge about programming with SCL. As you can see it can't be easier. Note how little code is required. PROGRAM first; {$V-} {No Length Checks for Strings. Mandatory for SCL} USES SCL; {Make SCL accessible} PROCEDURE handle_first; {This Procedure handles format 'first'.} BEGIN; Select_Format('first'); {Load the format from disk} Display_Format(0,0); {Display it in the upper left corner} REPEAT Handle_Format; {Complete Loop to handle format input} UNTIL Format_Done; {Either completed or abort key pressed} END; BEGIN; {of main} Select_Format_File('Sample1'); {initialize SCL and load the} {format file 'Sample1'} handle_first; {load,display and handle the format} Close_Formats; {terminate SCL } END. {of main} Appendix A, sample programs discussion page 192 Appendix A, sample programs discussion page 192 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Explanations of SAMPLE1.PAS Explanations of SAMPLE1.PAS Compiler Option '$V-' Compiler Option '$V-' This Option is required in any SCL program. More details about compiler options can be found in your 'TURBO PASCAL' manual. Without this compiler option specified SCL programs won't compile. USES Statement USES Statement "USES SCL;" makes SCL accessible from within this program. Main Program Main Program The first statement is Select_Format_File('Sample1');. This procedure Select_Format_File('Sample1'); initializes SCL and all required files. Since no file SAMPLE1.ERR exists in this case, SCL only initializes the error numbers (without the messages). 'Select_Format_File' is the first SCL statement to be executed and it appears only once in any program. Close_Formats; is the last SCL statement. It`closes all files and Close_Formats; frees the memory space previously used by SCL. Between these two statements, the procedure which processes the format in this program, Handle_first, is called. Handle_first Format Handling Format Handling The procedure 'Handle_First' performs the complete handling of our screen format. The first statement, 'Select_Format('first');' loads our format (with 'Select_Format('first');' the name 'First') from the format file into the format stack in memory. 'Display_Format(0,0);' then displays it on the screen starting at the upper left corner (Displacement 0,0). Then follows the actual format handling loop: REPEAT Handle_Format; UNTIL Format_Done; Appendix A, sample programs discussion page 193 Appendix A, sample programs discussion page 193 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The same Loop is used to process any format in SCL. The procedure Handle_Format is exited when any of the following occurs: Handle_Format * Before a new field on the format is initialized (=entered) * Before a field is left * Before the format is left (if it is finished) * and, optionally, depending on the format specifications, if a User Function Key has been pressed. User Function Key The boolean function 'Format_Done' returns FALSE as long as the 'Format_Done' format has not been finished. The format is considered to be finished if any one of the following conditions occurs: * All mandatory fields are filled in and either 'Escape' was hit or 'Return' was pressed while being in the last field. * The 'Abort' key (F10) is pressed. Apart from reading and writing fields and, the format handling loop is always the same, independent of the number and type of fields on a format. In fact, the above loop can fulfill the handling of any SCL any screen format. There is no need to define any logic for Help screens, Display of messages, Input error handling, field check and so on. All this is performed automatically by SCL as part of the Format Specifications which can be modified anytime via SFD. Note: This program does not provide the facility to read or to write Note: into fields. This will be covered in the next examples. What you could try : What you could try : 1. Run the program and see what happens. 2. Load the format into SFD and study its specifications. 3. Add a field to the format 'First' and/or re-specify existing fields. 4. Create your own format and modify the program to process it according to your requirements. Appendix A, sample programs discussion page 194 Appendix A, sample programs discussion page 194 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example 2 (OASIS Print Labels) Example 2 (OASIS Print Labels) _______________________________ This program captures address data from a screen format and uses it to output a specified number of mailing labels on your printer. Its basic structure is exactly the same as in example 1. For this reason only the new features are discussed. Notice the use of prompt and error message fields (called output output field in OASIS) at the bottom of your screen. field The error messages are held in a file called SAMPLE2.ERR. Failing to provide such file would still produce error numbers. In this very case SAMPLE2.ERR is just a straight copy of 'SCL.ERR' therefore exclusively contains messages for SCL internal errors handling rather than any user defined ones. References to other files description can be found in example 1. It consists of the following files: SAMPLE2.SCS : The format file, containing a single format. SAMPLE2.SCI : The index file to above. SAMPLE2.MSG : Contains all Field Messages. Field Messages SAMPLE2.PAS : The Turbo Pascal source program as listed below. OAS2LAB.EXE : Compiled version of SAMPLE2.PAS. The format file SAMPLE2.SCS The format file SAMPLE2.SCS It contains 3 formats: 'Address' : The label entry format. 'Autohelp': See the AutoHelp Feature and the note below. AutoHelp Feature 'Forhelp' : Specified as the format to be displayed if F1 is F1 pressed in the global specifications of 'Address'. Note: In case 'Autohelp' cannot be found, SCL displays the adequate Note: error message. Setting the SCL variable 'Autohelp_Set' to false would prevent its display. For the format 'Address', no Field Help Formats have been specified. Field Help Formats Appendix A, sample programs discussion page 195 Appendix A, sample programs discussion page 195 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Explanations of SAMPLE2.PAS Explanations of SAMPLE2.PAS The following describes all new SCL constructs introduced with this program. You can find the complete program listing on your distribution disks. Beep_Time:=2; Beep_Time:=2; This statement changes the duration of SCL's 'Beep' sound. By default this value is set to 4. Modifying it as shown above causes the 'Beep' to be shorter. Most of the other SCL default values can be modified in exactly the same fashion. REPEAT {stay in loop until 'Abort' is pressed} Get_Data; {display format and obtain data} IF NOT Format_Aborted THEN {format contains valid data} Print_Labels; {then print the desired labels} UNTIL Format_Aborted; {F10 ('Abort') key was pressed} 'Get_Data' is the familiar format handling loop, literally identical to the one discussed in example 1. 'Format_Aborted' is a boolean variable, which is TRUE if a format is aborted rather than normally completed. In other words, as long as 'Format_Aborted' is FALSE we know that the format was completed in the normal way and therefore contains valid data in agreement to the format specifications. 'Print_Labels' contains routines to read out the content of the format and print the appropriate mailing labels. Obviously, this can only be done if the format contains valid data (i.e has not been aborted). This sequence (Display of an empty format, reading the information and printing the desired quantity of labels) is repeated until the user terminates by pressing 'Abort'. Display_Format(X_Max DIV 2,Y_Max DIV 2); Display_Format(X_Max DIV 2,Y_Max DIV 2); X_Max is a function returning the maximum horizontal displacement possible for the current format. Y_Max returns the maximum vertical displacement. Hence 'Display_Format(X_Max,Y_Max)' would display a format in the lower right corner of the screen. Combined with 'DIV 2', the format is consequently displayed in the center of the screen. Appendix A, sample programs discussion page 196 Appendix A, sample programs discussion page 196 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Reading the Format Content Reading the Format Content The procedure 'Print_Labels' is also tasked to read the format content. Below you find a complete listing of this procedure. Its relevant contructs are discussed afterwards. PROCEDURE Print_Labels; {prints desired Qty of labels using the} VAR {data on format 'Address'} Wrkstr: String80; I : INTEGER; BEGIN; FOR I:=1 TO Nr(G_Cont(7)) DO {number of labels} BEGIN; IF G_Sel(1) THEN Wrkstr:=G_Cont(1) ELSE` {'Mr'} IF G_Sel(2) THEN Wrkstr:=G_Cont(2) ELSE {'Mrs'} IF G_Sel(3) THEN Wrkstr:=G_Cont(3); {'Miss'} WRITELN(lst,wrkstr,' ',g_cont(4));{concatenate the above} {with a space and the content of the 'Name' field} WRITELN(Lst); {Blank line} WRITELN(Lst,G_Cont(5)); {the street} WRITELN(Lst,Capital(G_Cont(6))); {the city} WRITELN(Lst,Charstring('=',LENGTH(G_Cont(6)))); {underline the city with '=' chars} WRITELN(Lst); WRITELN(Lst); {Two blank lines} END; {for loop} END; {procedure print_labels} Explanations to the above Procedure Explanations to the above Procedure As mentioned earlier in this manual, fields on formats can be read from the very moment a format is handled ('Handle_Format') until the next one is just about to be processed. In our example this is done at the completion of the format. 'G_Cont(n)' is a function returning the content of field 'n' in form of a string. 'Nr' is another function converting a string into an integer number. Therefore the construct 'Nr(G_Cont(7)' reads the content of field 7, converts it and returns it in form of an integer number. Please note that there is no need to check whether field 7 really contains an Integer number, since the relevant checks have already been performed by SCL in accordance with the specifications of the format itself. We can therefore be sure at this moment that the field contains an integer in the predetermined range (1..25 in this case). Appendix A, sample programs discussion page 197 Appendix A, sample programs discussion page 197 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual 'G_Sel(n)' is a function returning the Selected status of field 'n'. Selected Fields 1 to 3 are arranged into a Group of constants. This means that Group only one field can be selected at any time. Since we also have specified this group as Mandatory, we know that at least (and only) Mandatory one field has been selected. In our example, we find out which field this is and move its content ('Mr','Mrs' or 'Miss') to 'Wrkstr'. The content of field 4 (the name) is then added to it, seperated by a blank space, and finally the whole string is printed. Next, the content of field 5 (Street) is read and printed. The City (content of field 6) is printed in capital letters. The construct 'Capital(G_Cont(6))' elegantly performs this operation. Finally to underline the city with '=' characters, the construct 'Charstring('=',length(g_cont(6)))' returns a string of '=' characters with a length of the information contained in field 6 (City). Help system Help system As previously mentioned, the format file for this program contains 3 formats, two of them being 'Help screens'. As you probably realized, there is no logic whatsoever in the program to handle these screens. In order to feature an SCL program with help screens, all you have to do is to design them and add their names in the format specs of the format(s) they relate to. The Autohelp screen does not have to be Autohelp specified at all. SCL checks whether it exists and if it does, it is automatically displayed after a predetermined number of consecutive input errors has occurred. The name of the 'Autohelp' format must be identical to the one specified as 'Autohelp_Screen' in SCLs Global Declarations (Default: 'AutoHelp'). Note: Help screens relative to a Format are specified in that Note: Format formats Global Specifications. Help screens associated with one or Global Specifications more fields on a format are specified in the Field specifications of fields Field specifications the appropriate field(s). Input Messages Input Messages In order to display explanatory field input messages in an SCL program you just have to specify these messages in the Field Field Specifications of the appropriate field and enter the number of the Specifications field they should be displayed into in the Global Specifications of Global Specifications the format. Again, there is no logic required within the program itself for this feature to be incorporated. Appendix A, sample programs discussion page 198 Appendix A, sample programs discussion page 198 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Error Messages Error Messages System or user generated error messages are automatically displayed if the number of the field they should be displayed into is specified in the Global Specifications of the appropriate format. Global Specifications In case no error file (<Name>.ERR) exists, only the error number will be shown, otherwise the suitable message is displayed. What you could try : What you could try : 1. Run the program and see what it does. 2. Try to enter invalid data and see how the program reacts. 3. Load the format file into SFD and study the specifications of the three formats. 4. Run the program without the file SAMPLE2.ERR being available and see what happens if you make an input error. 5. Change the parameters 'Error Msg Field' and/or 'Input Msg Field' in the Global Specifications of the format 'ADDRESS' to 0 (zero) and run the program. See what happens. 6. Try to implement 'Field Help Screens' for 'ADDRESS'. 7. Allow the program to print up to 50 labels (25 is the current maximum). 8. Change some other Global SCL Parameters in the program, recompile and run it. 9. Add a field for the postal code on 'ADDRESS' and modify the program in such a way that it is printed on the label. Appendix A, sample programs discussion page 199 Appendix A, sample programs discussion page 199 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example 3 (OASIS Formats Stack) Example 3 (OASIS Formats Stack) ________________________________ This Program is a demonstration of the ability of SCL to stack formats. A format is pushed on the stack whenever a new format is loaded while the previous one is not yet finished. It is popped from the stack, i.e. restored as soon as the format on top of the stack is finished. In simple terms, this program works as follows: Load & Display format 'One'. Start handling format 'One'. Load & Display format 'Two'. Start handling format 'Two'. -- Keep doing the -- - same - - with formats - - 'Three' to 'Nine' - Load & Display format 'Ten'. Start handling format 'Ten'. Terminate format 'Ten'. Restore format 'Nine'. Continue handling format 'Nine'. Terminate format 'Nine'. -- and so on down -- -- to format 'Two'-- Restore format 'One'. Continue handling format 'One'. Terminate format 'One'. Terminate program. This means that while format ten is being loaded, nine unfinished formats are waiting in the stack to be continued. This may sound a lot, but SCL can simultaneously hold far more formats in its stack without any problems. There is no real limit apart from the size of your computer memory. If you should require more than 20 unfinished formats on the stack simultaneously, you must then adjust the Global Constant Global Constant 'Max_Heap_Screens' in SCL to reflect the required maximum number of formats. For guidelines to calculate the memory requirements of an SCL program please refer to 'System Resource Considerations' in the reference manual. Note: The above consideration only refers to the number of Note: unfinished Formats, formats that are finished before another format unfinished Formats is loaded do not take up any space on the stack. The Total Number of Total Number of Formats in a program is only restricted by your disk space capacity. Formats Appendix A, sample programs discussion page 200 Appendix A, sample programs discussion page 200 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Listing of SAMPLE3.PAS Listing of SAMPLE3.PAS PROGRAM Stackdemo; {$V-} {Disables LENGTH Checks FOR Strings} USES SCL; {invoke SCL} PROCEDURE Scl_Defaults; BEGIN; Beep_Time:=20; {Beep shorter} Auto_Help_Set:=FALSE; {No autohelp in this program} END; FUNCTION Up:BOOLEAN; BEGIN; Up:=FALSE; IF User_Function THEN {user function key pressed} BEGIN; IF (Active_Field = 1) AND {'Up' field} (Char_Code = Code_Return) THEN { wants to select field} BEGIN; Up:=TRUE; Char_Code:=Code_Noop; { SCL should not do anything} END { with this input character,} END; { i.e not mark the field as } END; { selected} PROCEDURE Do_Format(This_Name:String10;This_X,This_Y:INTEGER); VAR N, Next_Name:String10; Next_X, Next_Y :INTEGER; BEGIN; Select_Format(This_Name); {load it from disk} Display_Format(This_X,This_Y); {display it } Next_X:=This_X+2; {increase displacements} Next_Y:=This_Y+1; {for the next format to be loaded} REPEAT Handle_Format; {handle this format} IF Up THEN {user wants to go up} BEGIN; N:=Capital(This_Name); {capital letters} IF N = 'ONE' THEN Next_Name:='Two' ELSE {Which} IF N = 'TWO' THEN Next_Name:='Three' ELSE {format} IF N = 'THREE' THEN Next_Name:='four' ELSE {is} IF N = 'FOUR' THEN Next_Name:='Five' ELSE {the IF N = 'FIVE' THEN Next_Name:='Six' ELSE {next} IF N = 'SIX' THEN Next_Name:='Seven' ELSE {one} IF N = 'SEVEN' THEN Next_Name:='Eight' ELSE { ? } Appendix A, sample programs discussion page 201 Appendix A, sample programs discussion page 201 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual IF N = 'EIGHT' THEN Next_Name:='Nine' ELSE IF N = 'NINE' THEN Next_Name:='Ten'; Do_Format(Next_Name,Next_X,Next_Y); {Recursive} END; {call with new name and displacements} UNTIL Format_Done; {this format is finished.} END; {of Do_Format} BEGIN; {of main} Select_Format_File('Sample3'); {initialize SCL and load} {format file 'Sample2'} Scl_Defaults; {change some SCL defaults} Do_Format('one',0,0); {display&handle format 'one'} Close_Formats; {terminate SCL} END. {of main} Explanations of SAMPLE3.PAS Explanations of SAMPLE3.PAS The only new features in this sample program are a User Interrupt User Interrupt Procedure and the fact that a new format is called up while the old Procedure one is not yet finished. There is no need to emphasize how simply this can be achieved using SCL. User Interrupt Procedure User Interrupt Procedure We mentioned already in the explanations of Sample 1 that there were four conditions under which the procedure 'Handle_format' was exited. A User Interrupt Procedure is a user written routine which takes User Interrupt Procedure control at this point. To accomplish this, the appropriate routine (or a call to it) must be positioned within the format handling loop as follows: REPEAT Handle_Format; {---User Interrupt Routine----} UNTIL Format_Done; Hence the User Interrupt routine is always executed if User Interrupt routine 'Handle_Format' has been exited, i.e. one of the four conditions occurred. Among those four possible conditions one states that a User Function User Function Key has been pressed. Key This is actually the condition our user interrupt procedure is based on in this example. We want to interfere as soon as the program user tries to select field 1 (Up). In case field 2 (Down) is selected no action is taken and SCL terminates the format. (If no interference occurs in the case of field 1, SCL also automatically finishes the format since there are no further fields to be filled in). Appendix A, sample programs discussion page 202 Appendix A, sample programs discussion page 202 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The test pertaining to the occurrence of the above mentioned condition is performed by the boolean function 'Up'. Up returns TRUE if: 1. A User Function Key (in this case Return) was pressed and 2. field 1 (the 'Up' field) is currently selected. and 3. the current Input character (char_code) is 'Return'. If 'Up' is TRUE, the input character is replaced by a 'No-Op', which causes SCL to ignore it later on (SCL will then act as if the Return key was never pressed and consequently wait for User input). If this does not happen SCL would, as soon as it regains control, carry on from where it left off and consequently mark field 1 as 'Selected' before it automatically terminates the format. If 'Up' returns TRUE, a recursive call to 'Do_Format' is made and the whole process starts over again with the next format. If one format is finished, i.e 'Down' has been selected or F10 (Abort) has been pressed then SCL automatically restores the previous format from the stack. What you could try: What you could try: 1. Load the format file into SCL and study the specifications of one of the formats (they are all identical except format 'Ten', which does not have any fields). 2. Remove the statement 'Char_code:=Code_Noop;' from the function 'Up', recompile and run the program and see what happens. 3. Write your own program without recursion and with only 2 or 3 formats (you may use the format file from this example). Appendix A, sample programs discussion page 203 Appendix A, sample programs discussion page 203 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example 4 (OASIS Automatic Disk Menu) Example 4 (OASIS Automatic Disk Menu) ______________________________________ This example program is quite a useful DOS utility program. It displays all executable files of the current directory along with all subdirectories and the parent directory (if applicable) on a screen format. You can execute any program from the current directory or move to a different subdirectory by just pointing to it. When compared to the three previous examples, this one is fairly complex and employs a lot more SCL features. Despite (and maybe especially because of) the fact, that SCL has certainly not been designed to develop DOS utilities, this example demonstrates and highlights its tremendous power and flexibility. The main new features exhibited in this program are: - The 'Execute' and , 'ExecuteDos' routines. - Background processing. - More sophisticated User Interrupt Procedures. The relevant components of the program will be discussed in the following. The Procedure Menu The Procedure Menu This program only uses one Format and the procedure handling this format is called 'Menu'. It uses some advanced technics we have not covered yet. In the previous examples 'Display_format' was immediately called after 'Select_format' whereas here the format is first 'filled' before being displayed. The procedures involved in this task are 'Init_Dir_Search', 'Display_Files' and 'Tell_Result'. Apart from this, within the actual Format handling loop, you find a Format handling loop statement which invokes a User Interrupt Procedure ('Handle_Key') in User Interrupt Procedure case a User Function Key has been pressed. If the format has been User Function Key finished (and was not aborted), the procedure 'Do_Work' is executed. All the above mentioned procedures are described in detail on the following pages. Appendix A, sample programs discussion page 204 Appendix A, sample programs discussion page 204 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Init_Dir_Search Init_Dir_Search This procedure initializes the parameters for our Directory search. It sets the boolean variable 'First' to TRUE and the search mask to '*.*' (all files). Note: 'First' is a parameter for the directory search which if TRUE, Note: causes it to initialize a new search, i.e to find the first filename matching the specified mask. Once the first file has been found, it is set to false and subsequent searches will search for the remaining files. Display_Files Display_Files The first part of this procedure is a REPEAT..UNTIL loop which calls 'Dir'. If 'Dir' returns a result of 0 (zero), meaning that a filename matching the mask was found, the procedure 'Pick_it_if_we_need_it' is called, which determines whether this file is either an executable file or a directory entry. If this is the case, the file name is moved to the first available field and the field count is increased by 1. In order to determine whether the file found should be displayed on the format, we access the SCL variable 'Dta' (For details about the content of 'Dta' please refer to 'Advanced Programming Technics'in the reference manual). We exit the REPEAT..UNTIL loop under any one of the following two conditions: either the format is full or there are no more files matching the mask. In the latter case we reinitialize 'Dir' by calling 'Init_Dir_Search' again and we also blank the remaining fields on the format. In every case, we also make a note of the highest field on our format containing a filename entry. Now that's where the real tricky part starts: On this format we want to have two active fields at the same time, one being the field containing the filename to be executed and the other one where the optional parameters can be entered. SCL can only have one active field at a time, therefore we have to cheat somehow. One way to achieve this is to declare all the fields holding filenames (2 to 46) as 'Output' fields and manipulate these fields independent from the normal SCL field processing. This just leaves, what SCL concerns, field 49 as the only cursor accessible field on this format which is consequently active, i.e ready for input, anytime the format is displayed. In order to highlight the currently chosen filename field, we use the 'selected' field attribute. The procedure 'Handle_Keys', which monitors the 'arrow' keys, determines which filename is to be highlighted next and the highlighting itself is performed by the procedure 'New_Field'. Appendix A, sample programs discussion page 205 Appendix A, sample programs discussion page 205 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Handle_Keys Handle_Keys This procedure acts on all User Function Keys defined for this User Function Keys format. In case F9 is pressed, the field holding the currently highlighted filename is deselected and 'Display_files' is called to refill the format. In case the display of the current directory is not yet complete, ('first' is FALSE) the remaining entries are searched to be displayed now, otherwise a new search cycle is initiated to display the first page of file names. In case, one of the 'arrows' or 'Home' or 'End' is pressed we determine the next field (file name) to be highlighted and call 'Next_Field' to do it. The next two keys are only intercepted for user convenience: If 'Escape' is pressed, it is replaced by 'F10' (Abort) which subsequently causes the program to be terminated. If 'Return' is pressed and the parameter field (49) contains spaces this key is replaced by an 'Escape' character, which causes the format to be terminated instantly. The reason for this is that SCL would interpret 'Return' in this case as a command to switch field 49 to 'Edit Mode' and we would have to press 'Return' (or 'Escape') again to finish the format, therefore this manipulation saves the user an additional keystroke. With the exception of the last two cases we want SCL to ignore any other key depression by substituting 'No_Op'. New_Field New_Field This procedure is called with two parameters, the field currently highlighted (due to be deselected) and the new field (the one about to be selected, i.e highlighted). This task is performed by the first two statements. Once this is done, 'current field' matches the new field now being highlighted. In the same time frame three more fields need to be updated but instead of being processed here it is treated as a background task because another 'Arrow' key could also already be pressed. In this case priority is given to handle this key first before attempting to update any one of the three fields. By making this task a background job we ensure that it is only done when spare time is available, without delaying any pending keyboard input. In order to notify the Background processing procedure that updates Background processing procedure are to be carried out , three boolean flags are set, one for each field to be revised. Appendix A, sample programs discussion page 206 Appendix A, sample programs discussion page 206 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Do_Work Do_Work This procedure first fetches the file name from the field currently highlighted. In case of a directory entry it changes the current directory accordingly. If we are dealing with an executable file instead it first builds a string out of the filename (including path) and the parameter entry and then executes this file. Depending on whether it is an '.EXE' file or not, 'Execute' or 'ExecuteDos' is used. The reason for this is that all '.BAT' and some of the '.COM' files (mainly some external DOS commands) require COMMAND.COM to be present while '.EXE' files can be started directly. On return from the previously executed program, a check for successful execution is done and if this is the case a prompt asks the user to press 'Return' to go back to the menu program (The reason for not going directly back is to give him a chance to read the screen content). In case of problems during execution we directly go back to the menu program and 'Tell_Result' displays an appropriate error message. Tell_Result Tell_Result This procedure simply checks whether 'Execute' or 'ExecuteDos' caused a result code indicating an error. If an error occurred the relevant (user defined) error message is displayed in field 50 and a 'beep' is initiated. Note: More information on user defined error messages can be found Note: under 'Advanced Programming Technics'in this appendix. LP_Background_Task LP_Background_Task This is assigned as a SCL background Task via the 'LP_Background_Pointer:=@LP_Background_Task;' statement in the main body of the program. It is called by the SCL procedure 'Handle_Format' whenever there is no keyboard input pending and no other work needs to be done. This procedure is used here to update fields 46,47 and 49 after a different filename has been selected by the user. It is based on the simple principle that whenever the procedure is entered all three flags set by 'Next_Field' are checked. If one of these flags is found to be TRUE the pertinent update procedure is performed and the flag is then set to FALSE. The update procedures themselves are clear and easy to understand and therefore not separately described here. Appendix A, sample programs discussion page 207 Appendix A, sample programs discussion page 207 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Example 5 (OASIS SCL Demo) Example 5 (OASIS SCL Demo) ___________________________ This program is a little demo giving an overview on some SCL features. Although 14 different screen formats are handled it remains a rather simple program. It consists of a main menu proposing a selection of 8 different demos plus the possibility to terminate the program. In order to demonstrate background processing it also features a display of time and date on each format. The following is a detailed explanation of its various procedures. Menu Menu The Menu procedure is very straightforward. The menu format is processed using the very same basic Format Handling Loop already Format Handling Loop described in example 1. Once the format is finished, upon detection of the selected field the corresponding demo procedure is called up. In the case field 13 being selected, the boolean variable 'Progend' becomes TRUE which then causes the program to exit the REPEAT..UNTIL loop and subsequently terminates the demo program. The reason for using this boolean variable rather than 'UNTIL G_Sel(13)' is simple: Just imagine you would come from a demo format where field 13 was selected. Since R_Ptr would still point to this demo format, R_Ptr 'G_Sel(13)' would access field 13 on this format rather than on our menu. We must therefore make sure that we pass 'Handle_Format' (which adjusts R_Ptr to the menu again) before any attempt to read a field. This is realized by simply including the 'G_Sel' into our 'case' statement. Five out of the eight different demos are performed by just calling the procedure 'Do_Format' with the appropriate format name while the other three demos required some additional programming. 'Do_Format' is a simple procedure which selects a format, displays it and then handles it. In order to be able to blank the format when completed the User Interrupt Procedure monitoring 'End_Of_Format' is employed. The other three demos are a bit more complicated and will therefore be discussed in detail. Appendix A, sample programs discussion page 208 Appendix A, sample programs discussion page 208 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Country Demo Country Demo Country demo demonstrates SCL's capability to work with the DOS country information. When compared with 'Do_Format', the main procedure of country demo offers two additional features. The first procedure was added to set up the fields before the format was actually displayed on screen ('Update_Fields'). The second procedure acts on 'End_of_field'-User Interrupts. Interrupts Procedure Update_Fields Procedure Update_Fields This procedure accesses some of the Country dependent Information provides by SCL and writes it to the proper fields on the format. Please note that the numeric (integer) values are converted to strings using the 'St' function. Procedure Handle_End_of_Field Procedure Handle_End_of_Field This procedure is the actual heart of 'Country demo'. Below you can examine its listing. All programming details are discussed afterwards. PROCEDURE Handle_End_Of_Field; {user interrupt procedure} BEGIN; IF Active_Field = 4 THEN {new country code entered} BEGIN; IF G_Cont(4) > ' ' THEN {not blank} BEGIN; Scl_Country:=Nr(G_Cont(4)); {move it to SCL_Country} Get_Country; {get country information} IF (Country <> Scl_Country) AND (Scl_Country > 0) THEN BEGIN; {invalid country code was entered} Glb_Error:=24; {error number to SCL} Scl_Country:=Nr(G_Cont(5)); {restore old country} Get_Country; {get country info} END ELSE {country code was valid} Update_Fields; {display new country info} END; END; END; Appendix A, sample programs discussion page 209 Appendix A, sample programs discussion page 209 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The first two 'IF' statements ensure that we are in field 4 and that this field contains data. If this is the case, the content will be read, converted to an integer and placed into 'SCL_Country'. We then call the SCL procedure Get_Country' which accesses the DOS country information and updates the relevant SCL variables accordingly. 'Get_Country' acts as follows: If 'SCL_Country' contains 0 (the default value) it borrows the country information according to the setting of your computer (Country=xxx statement in CONFIG.SYS). If SCL_Country contains any other value (a Country-code) then SCL is set up according to this code. Once 'Get_Country' has been called, a check for country code validity is performed. It is valid when either the value returned in 'Country' is equal to 'SCL_Country' or if 0 was specified for 'SCL_Country'. In case of invalid country code, the one previously used is restored from field 5 (we wrote it to this field in 'Update_Fields'), and 'Get_Country' is called again with this latter value in 'SCL_Country' to restore the variables in SCL back to valid information. In addition, 'Glb_Err' is set to an error number pointing to a message in SAMPLE5.ERR stating that an invalid country code was entered. Since 'Glb_Err' returns a value different from 0 (zero), 'Handle_Format' will enter its input error routine, beep, display the error message and also refuse the attempt to leave field number 4 until a valid country code is keyed in. In case of a valid code 'Update_Fields' is called once more to write the new information into the corresponding fields. Note: Further details about user generated error messages and the Note: use of 'Glb_Err' can be found in this appendix. Appendix A, sample programs discussion page 210 Appendix A, sample programs discussion page 210 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Date Demo Date Demo Date Demo demonstrates most of the date/time routines in SCLn With the exception that the field update procedure is called 'Prefill' here, the main procedure of 'Date_Demo' is identical to the one described in 'Country_Demo'. However both 'Prefill' and the user Interrupt Procedure contain a user Interrupt Procedure great number of new constructs which will be discussed in the following pages. Prefill Prefill This procedure fills some fields with information about todays date. First, the SCL routine 'Get_Date' is called to retrieve todays date as integer values. Then the 'day of week' value is converted to the actual name which is effectively written to field 4. The date is then converted into a julian date. Since the function 'St' cannot be used with REAL numbers, 'STR' is used instead to convert the julian date to a string before it finally can be written to field 5. Handle_End_of_Field Handle_End_of_Field User Interrupt Procedure is invoked whenever a 'End_of_Field' Interrupt Procedure condition occurs and also in the case of fields 6 and 15. Field 6 is the one where the user can enter a date. Upon leaving this field, a check for data entry is performed and if something has been keyed in the following occurs: The procedure 'Check_Date' checks the date entered for validity and converts it to three integers for year, month and day. (Please note, that the date is checked according to the country information currently used. In the case of USA (1) the date is interpreted as MMDD whereas for most other countries it is DDMM). If the date entered is invalid, 'SCL_Err' is set to point to a user defined error message in SAMPLEu.ERR, which causes SCL to display this message, beep and to reject the attempt to exit this field. In addition to this, fields 7 to 14 are blanked out. If the date entered is found valid, the procedure 'Update_User_Date' is called which in turn does some calculations and writes the results to fields 7 to 14. For field 15 the process is similar, in this case the user is supposed to enter a valid time and if he does so, 'Up date_User_Time' is called to analyze the time entered and to write appropriate information to fields 16 to 19. If the time entered is invalid, a sequence identical to the one described for the date takes place, the only difference being the error message. Appendix A, sample programs discussion page 211 Appendix A, sample programs discussion page 211 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Update_User_Date Update_User_Date This procedure uses most of the SCL date related routines. It first writes the values for day, month and year of the date in field 6 (and decoded by 'Check_Date') to fields 7, 8 and 9. Then these three values are converted into a date string by 'Date_String' and written to field 10. The julian date is calculated, converted to a string using 'STR' (St cannot be used for REAL numbers, only for Integers) and written to field 11. After this, the number of days between today and the date entered is calculated by simply subtracting them from each other and converting the result to a positive number. This value is written to field 12. The procedure 'weekday' is used to calculate the 'day_of_week'. The result, an Integer number between 0 (sunday) and 6 (saturday) is then converted into the matching day name and written to field 13. 100 days are then added to the julian date, the result is converted back into year, month and day via the procedure 'Normal_Date', formatted with the function 'Date_String' and finally written to field 14. Update_User_Time Update_User_Time This rather simple procedure converts the integer values for hours, minutes and seconds of the time entered into field 15 to strings and writes them to fields 16, 17 and 18. These values are then converted to a formatted time string by the function 'Time_String' and written to field 19. Appendix A, sample programs discussion page 212 Appendix A, sample programs discussion page 212 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Special Fields Demo Special Fields Demo Main procedure Main procedure This procedure is identical to those used for the 'country' and 'date' demos with one exception however; it embeds an additional User User Interrupt Procedure, which monitors the keyboard keys. This User Interrupt Procedure User Interrupt Procedure, 'Handle_User_Function' is probably the most Interrupt Procedure interesting part of this demo because it reveals some useful tricks which you will find most helpful when writing your own application programs. Handle_User_Function Handle_User_Function This procedure deals with fields that have the 'Char Check' field attribute set to TRUE. It is therefore executed whenever one of these fields is active and any keyboard key is pressed. Each field will be discussed separately. Note: The reason for using 'Char Check' here is quite simple: in Note: this demo we have to take into consideration far more keys than the maximum number that can be specified as 'User Functions' on one format (10, plus any of the function keys). In a real world program it would probably be preferable to specify 'User Function Keys' because, beside the fact it is faster ('Handle_Format' is not interrupted for each single key) it also can save you programming work since you would know that the key pressed must belong to the specified set. Field 5 If the input key is a 'Space' the content of the field is changed to something else. In this example we only use three different possibilities but in a user program it could also be any other number. This field shows a nice way to make programs more userfriendly which, in many cases can also save an additional menu. Field 6 While this field is active we check if one of a specified set of keys has been pressed, and if this was the case, an appropriate string is written into the field. This construction can equally be used in the same manner as the one demonstrated with field 5. Appendix A, sample programs discussion page 213 Appendix A, sample programs discussion page 213 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Field 7 When active this field displays the ASCII Code of each key pressed with the exception of 'Return' which moves us to the next field. The SCL internal character code notation is as follows: if the key creates a two byte code (an ASCII Code preceded by a 'ESC' character), 1000 is added to it, otherwise the normal ASCII value is kept. Field 8 The handling of this field is simple, each input character (if it is not a 'two byte key') is converted to upper case and then displayed. This can be useful in many application programs as well. Note: In all cases, where you don't want SCL to take any action on a Note: character, simply replace it by 'Char_NoOp'. SCL will then just ignore it. Handle_End_of_Field Handle_End_of_Field This procedure monitors field 4 and checks whether it is selected or not. If selected it writes 'Yes' to its content, otherwise 'No'is written. Similarly the same method can be used in all cases where the objective is to display the state of a field with text rather than with a display attribute. Background Processing Background Processing The capability to support background processing is one of the most powerful features of SCL. In this example program it is used to display the time and the date (obviously, you can do a lot more with it). In this example program the current date and time are displayed in two fields on each format and 'LP_Background_Task' is used to update these fields constantly. 'LP_Background_Task' simply checks whether the actual time and date is still reflected by the content of the two fields and if this is not the case, updates them. Appendix A, sample programs discussion page 214 Appendix A, sample programs discussion page 214 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Appendix A, sample programs discussion page 215 Appendix A, sample programs discussion page 215 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Screen Control Language The Screen Control Language (SCL) (SCL) SCL System Details SCL System Details OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Service Routines Service Routines Interrupt Service Routines are routines which are called to handle events within your computer. They are normally located in the computers BIOS (Basic Input Output System). A user program can take over the handling of interrupts. This is accomplished by placing the address of its own interrupt routine into the BIOS Interrupt Vector table. SCL takes control of two interrupts with its own routines: The clock tick interrupt (Interrupt 1CH) The clock tick interrupt (Interrupt 1CH) This interrupt is called by the BIOS time handling routines (Hardware Clock) 18.2 times per second (about once every 55 milliseconds). Every time Interrupt 1CH is called by the BIOS, control is passed to the routine 'Clock_ISR' in SCL which then performs the necessary SCL internal functions before control is returned to BIOS. These functions are to control the duration of the 'Beep' Sound and the field blinking frequency (see also the description of 'Blink_Count'). By using an Interrupt service routine instead of a normal SCL procedure to manage these tasks it is ensured that they are performed entirely independantly of the logic of your application program and SCL itself. Hence a lot of unnecessary overhead is avoided because instead of waiting for an event, SCL can perform other functions. Consider the following example of a typical 'Beep' routine: PROCEDURE Do_Beep; BEGIN; SOUND(500); DELAY(250); NOSOUND; END; If SCL was programmed like this, one would have to wait 250 milliseconds for this routine to exit without being able to do anything else. This would not only slow down the program considerably but it would also make background tasks like datacom etc.. virtually impossible. For this reason, the 'Beep' routine in SCL looks in principle as follows: PROCEDURE Beep; BEGIN; SOUND(Beep_Frequency_1); Beep_Counter:=Beep_Length; END; Appendix A, SCL system details page 217 Appendix A, SCL system details page 217 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Instead it is left to 'Clock_ISR' to decrement 'Beep_Counter' and to issue a 'NOSOUND' when the counter has reached 0 (zero). 'Clock_ISR' is installed by the routine 'Get_Clock_Tick' which is called by 'Select_Format_File' during the initialization of SCL. It is deinstalled (the pointers in the BIOS Interrupt Vector Table are restored to their original values) by either 'Close_Formats' or, in case of an error, by 'Fatal_SCL_Error'. The Data Communications Hardware Interrupt (Interrupt 0CH) The Data Communications Hardware Interrupt (Interrupt 0CH) This interrupt is handled by a SCL Interrupt Service routine in case your program involves data communications. It is a Hardware Interrupt signalling several conditions on the asynchronous communications port (COM1:). SCL uses this interrupt in its 'Low Level' data communication system to recognize if a character has been received on the RS232 interface and to read this character into its receive buffer. For further information on SCL's Data communications routines please refer to Appendix B. Note: Do not call a Interrupt Service Routine directly from your Note: program because it could hang the system and make a reboot necessary. The same applies for the ISR installation and deinstallation routines. Appendix A, SCL system details page 218 Appendix A, SCL system details page 218 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Background Processing Tasks Background Processing Tasks SCL provides two 'userhooks' for background processing tasks, one referred to as 'Low Priority' and the other as 'High Priority'. SCL provides these 'userhooks' in form of two pointer-variables, 'LP_Background_Pointer' and 'HP_Background_Pointer'. The Procedures these pointers point to are performed by SCL as Background Tasks. If SCL is initialized, both pointers point to dummy procedures within SCL which only contain a begin-end statement. These pointers can be redirected by you to point to any other procedure which is subsequently performed as background task by SCL. You can basically specify any procedure as a background task as long as you follow a few rules: The procedure may not contain any statements which could cause to wait it on an event, like for example 'keypressed'. A Background Procedure must be compiled with the 'Force far calls' option active ( {$F+} ). Both Background Tasks are being called from within the SCL procedure 'Handle_Format'. 'Handle_Format' is event driven. This means that a loop containing several conditional statements is continuously executed and whenever one of the these conditions becomes TRUE the appropriate task is performed. In addition to the background procedures, the other tasks are reading the keyboard if a key is pressed, processing an input character and updating field attributes. The logic within this loop is as follows: 1. Start 2. Perform the High Priority background task (unconditionally, once per loop). 3. If a key is pressed then read it into the keyboard buffer otherwise, 4. If a character is still being processed then carry on processing it (processing a single character takes between 2 and 4 loops depending on its type) otherwise, 5. If the keyboard buffer is not empty then fetch the next character otherwise, Appendix A, SCL system details page 219 Appendix A, SCL system details page 219 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual 6. Perform the Low Priority Background Task and, if a field attribute needs to be updated then update it. 7. Go to Start. As you can see, the High Priority Background Task is executed unconditionally in every loop and the Low Priority Background Task is executed only in case no keyboard input is waiting to be processed. Due to the dynamic nature of such a loop, no exact figures can be given on how often the Background Tasks are executed. As a rule of Background Tasks thumb, on a plain PC (4.77 Mhz) HP_Background_Task is executed about 1300 times per second and in a fast AT as much as 10000 times per second (assuming that the processing time required for the background task itself is negligible). The figures for Low Priority Background Tasks are roughly the same if the system is idle (typically most of the time) but can dramatically drop at times of heavy activity. There are certain rules you should follow if you use Background processing in order to avoid slowing down a program: 1. Split any task into as many subtasks as possible, for example, if you want to write output to a printer, write one character at a time rather than the whole line. 2. Exit the Background Task procedure as quick as possible if no work has to be performed (Preferably use the 'Exit' statement). 3. Use High Priority Background tasks only when you have to. Most jobs can well be accomodated with Low Priority. 4. Don't use any statements in a background procedure which wait on an event like 'Repeat until keypressed' or 'Delay(n)'. 5. If you use a High Priority Background Task, its execution time should typically not exceed a few milliseconds, otherwise you may slow down your program dramatically. The following is a short example intended to give you an idea how to use 'Background Tasks'. Further examples can be found in some of the 'Sample' programs, namely SAMPLE4.PAS, SAMPLE5.PAS and SAMPLE7.PAS. Appendix A, SCL system details page 220 Appendix A, SCL system details page 220 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Program EXAMPLE; uses Printer,SCL; {$F+} {Force far calls} Procedure My_Background_Task; {prints asterixes on printer while} begin; {format is being handled} write(lst,'*'); end; {$F-} {reset far calls} Procedure do_format; begin; select_format('main'); display_format(0,0); repeat handle_format; until format_done; end; begin; select_format_file('myformats'); lp_background_pointer:=@My_Background_Task; {assigns it as LP } Do_Format; { background task} Close_formats; end; Appendix A, SCL system details page 221 Appendix A, SCL system details page 221 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual READING AND WRITING FIELDS READING AND WRITING FIELDS For a better comprehension of the mechanisms that govern the handling of formats the following scenario will be used as working platform: 1. Select format A and display it on the screen. 2. Select format B and display it on top of format A. 3. Exit format B restoring format A in its integrity on the screen. 4. Exit format A 5. Select format C and display it on the screen. 6. Exit format C. For each step a status of the various pointers is given along with any relevant annotation. Select_Format_file('thisfile'); ** STEP 1 ** ** STEP 1 ** The format stack is still empty and all S_Ptr, R_Ptr, W_Ptr do not point yet to any valid format. In other words no field can be accessed, whether read or written at this point in time. Select_Format('A'); Format 'A' is loaded into record 1 of the format stack. Both S_Ptr and W_Ptr point to this record and take 1 for value. From now on it is possible to write to format 'A'. However read of format 'A' is still not possible since R_Ptr does not point yet to a valid format. Display_format(0,0); This statement does not affect the value of the pointers. Repeat Handle_Format; This is where R_Ptr is adjusted making a read from format 'A' possible. All three pointers are now pointing to format 'A' and have a value of 1. Select_Format('B'); ** STEP 2 ** ** STEP 2 ** A second format is now selected coexisting with format 'A' which remains on the stack with entry number 1 while format 'B' is loaded to the top of the stack assigned to record number 2. As a result both W_Ptr and S_Ptr point to format 'B' and have 2 for value while R_Ptr is still looking at format 'A' with its value remaining unchanged (1). For this reason the construct W_Cont(5,G_Cont(4)); is interpreted as read the content of field 4 of format 'A' and place it into field 5 of format 'B'. By manually altering the W_Ptr value (ie. 'W_Ptr:=1') it is still possible to write to format 'A' should you fancy it. Display_format(0,0); Pointers keep their previous value. Repeat Handle_Format; All three pointers are now pointing to format 'B'. UNTIL Format_Done; ** STEP 3 ** ** STEP 3 ** This statement finishes format 'B' letting SCL restoring format 'A'and implicitly having both S_Ptr and W_Ptr point to format 'A' with a value of 1 again. R_Ptr however is still pointing to format Appendix A, SCL system details page 222 Appendix A, SCL system details page 222 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual 'B' keeping its value unchanged (2). The construct 'W_Cont(5,G_Cont(4)); would now mean: read the content of field 4 of format 'B' and place it into field 5 of format 'A'. UNTIL Format_Done; ** STEP 4 ** ** STEP 4 ** This finishes format 'A' and both W_Ptr and S_Ptr do not any longer point to a valid format and have 0 for value. The R_Ptr however still point to format 'A'. The construct 'WrkStr:=G_Cont(5) would then read the content of field 5 on format 'A' into WrkStr. Although both formats are now finished, this does not mean that they were destroyed but still remain in the stack. For that matter a manual manipulation of R_Ptr is genuinely possible and effective (ie. 'R_Ptr:= 2'; to point to format 'B'. Select_Format('C'); ** STEP 5 ** ** STEP 5 ** This loads format 'C' to record 1 of the format stack physically overwriting format 'A' previously sitting there. Both S_Ptr and W_Ptr point to format 'C' taking 1 for value while R_Ptr does not point to any format any longer and becomes 0. Display_format(0,0); The pointers are not affected. Repeat Handle_Format; Now all three pointers point to format 'C' and have a value of 1. UNTIL Format_Done; ** STEP 6 ** ** STEP 6 ** At this moment both S_Ptr and W_Ptr no longer point to a valid stack record and have the value 0. R_Ptr however still points to format 'C' and keep its value of 1. The stack itself has format 'C' in record 1 and format 'B' in record 2. Any subsequent format would load on top of format 'C'. As seen in this scenario, unfinished formats always remain in the stack while finished formats stay in the stack until they are overwritten by new formats. While a format is still in the stack, its content can always be accessed by manual modification of the appropriate pointer to the desired record number. Appendix A, SCL system details page 223 Appendix A, SCL system details page 223 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL Input Character Processing SCL Input Character Processing All Input Character processing in SCL is done by 'Handle_Format'. The sequence of events is as follows: 1. Read a Character from the Input Buffer into 'Char_Code'. Then go to 2. 2. If Char_Code is specified as a User function Key in this format User function Key or if Char Check is specified for the active field then set Char Check 'User_Function' to TRUE and exit 'Handle_Format' and go to 3 upon return; otherwise go directly to 3. 3. If 'Glb_Err' > 0 or char_Code = NoOp then discard Char_code and go to 1; otherwise if Char_Code is invalid then perform the input error routine and then go to 1; otherwise go to 4. 4. If this character is to be displayed, display it and then go to 1; otherwise go to 5. 5. If Char_Code is a 'Help' key then perform the appropriate Help routine and then go to 1; otherwise go to 6. 6. If Char_Code terminates the current field then perform the internal validity check as specified for this field. In case of failure perform the error routine, discard the character and go to 1; otherwise set 'End_of_Field' to TRUE, exit 'Handle_Format' and go to 7 upon return. 7. If Glb_Err > 0 then perform the error routine, discard the character and go to 1; otherwise, if char_Code = NoOp then go to 1; otherwise terminate the field and go to 8. 8. If this character terminates the format as well then go to 10 otherwise go to 9. 9. Determine the next field and initialize it (make it the 'Active Field'). Then set 'Begin_of_Field' to TRUE and exit 'Handle_Format. Upon return go to 1. 10. Perform the internal format end check (all mandatory fields filled in). If this fails, perform the error routine, discard the input character and go to 1; otherwise set 'End_of_Format' to TRUE and exit 'Handle_Format'. Upon return go to 11. 11. If 'Glb_Err' > 0 then perform the error routine, discard the input character and go to 1; otherwise if Char_Code = NoOp then go to 1; otherwise terminate the format. Appendix A, SCL system details page 224 Appendix A, SCL system details page 224 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Error Message File The Error Message File The file <Name>.ERR is the only SCL file not automatically created by SFD. It is a simple ASCII text file and can be modified with most word processors (or Turbo Pascal, for example). The first 21 records and records 36 to 39 are occupied by SCL internal error messages, all other records are available for your own use. You find a 'virgin' errorfile only containing the SCL internal error messages on your distribution disks under the name 'SCL.ERR'. The contents of SCL.ERR is also listed in Appendix B. You can simply copy this file to <Workfile>.ERR and then add your own messages as required. The records may contain any text and are not bound to a special format. The only limitation is that their maximum length may not exceed 70 characters. On top of SCL internal error messages, this file can be used to store your own error messages as well as any other strings you may require in your program. All you have to do to display a specific message in the event of an error occuring while processing a format is to set 'Glb_Err' to the appropriate record number. If you just want to access a string stored in the error file you can use the SCL function 'Sys_Msg'. Since during execution of an SCL program, all records of this file are stored in the heap memory, access to them is very fast. Please note that an error file is optional for an SCL program. If it is not found during the initialization of SCL, the appropriate record spaces in the heap are initialized with just their corresponding record number which will then be displayed should an error be found. Example: Example: Select_Format('X'); W_Cont(2,Sys_Msg(18)); {writes content of record 23 to field 2} Display_Format(0,0); REPEAT Handle_Format; IF End_of_Format THEN IF not (G_CONT(1) in ['A'..'D','a'..'d']) THEN Glb_Err:=43; {SCL will execute its error routine and} {display the string stored in record 43 in} {the error message field, the attempt to} {terminate the format will be refused} UNTIL Format_Done; Note: See also Programming sample 4, 'Tricks & Tips' and 'System Note: Resource considerations'. Appendix A, SCL system details page 225 Appendix A, SCL system details page 225 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual SCL - System Resource Considerations SCL - System Resource Considerations Disk Access Disk Access SCL reads its formats from disk. This process can be speeded up considerably by including a 'BUFFERS=NNN' statement into the CONFIG.SYS file. It is recommended to set the number of buffers to at least 20 on computers running SCL programs. Another effective way is the use of a RamDisk or, preferably, a Disk Cache Software (for example 'Lightning' from PCSG Inc). Processor Requirements Processor Requirements SCL performs well on any compatible PC system. Due to a highly optimized program layout, the speed differences to be expected between a 8088 and a 80286 based system are relatively small if compared with some other programs. The performance of an 8088 System running an SCL program can be increased considerably by exchanging the 8088 processor against a NEC V20. The V20 features, beside being fully compatible with the 8088, a highly optimized string handling which results in about 20 % performance improvement if used with SCL programs. Format File -Disk Space Requirements Format File -Disk Space Requirements The format file occupies 4608 bytes per format. This means that a 360 KB Floppy can hold a format file with up to 79 formats. The other SCL files are relatively small and typically only take up a few kilobytes all together. SCL Code Space Requirements SCL Code Space Requirements SCL takes up about 15 to 35 KB of space in the code segment (Dependent on the number of SCL routines you use). SCL Data Space Requirements SCL Data Space Requirements SCL stores most if its informations in the Heap, therefore the actual space required in the data segment is relatively small. It depends largely on whether Datacom is used or not and is typically between 3.5 KB (no datacom) and around 10 KB if datacom is used. Within the heap memory, the static space required by SCL is about 12 KB plus the size of the file "<name>.MSG". In addition to the static space, SCL`dynamically allocates during program runtime 4.6 KB for every format required to be stacked (refer to SCL Details for more informations on the format stacking mechanism). Appendix A, SCL system details page 226 Appendix A, SCL system details page 226 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The heap shares its space with the program stack. There is no exact way to predict the size of the stack required for a program. It largely depends on the program's logical structure, especially if recursive routines are used. The only way to find it out is by 'trial and error', i.e by decreasing it until the program does not run anymore. Total Memory Requirements Total Memory Requirements Example1: A small SCL program with about 5 to 10 screen formats, no Example1: datacom and 100 field input messages. Format stacking is assumed to occur to up to 3 levels, i.e max 3 unfinished formats can be on the stack while a fourth one is being processed. Example2: A very large program with 50 to 100 screen formats, 500 Example2: field messages, datacom and extensive data space requirements. Up to 10 formats are assumed to be stacked on the heap. The code and data requirements quoted represent the maximum values allowed in Turbo Pascal programs. The approximate total memory required to run the above two example programs can be roughly calculated as follows: Example1 Example2 ----------------------------------------------------------------- Code space (approx) ............................. 50 KB 90 KB Data space (approx) ............................. 10 KB 64 KB Program Stack (approx) .......................... 5 KB 40 KB Heap space (static) ............................. 12 KB 12 KB Heap space (field messages) ..................... 7 KB 36 KB Heap space (format stacking) .................... 14 KB 46 KB Static space required by DOS (approx) ........... 35 KB 35 KB ----------------------------------------------------------------- Minimum total memory required to run (approx) .. 133 KB 323 KB Example 1 could run in a 256 KB system with no problems and would Example 1 even permit another 90 KB of memory to be used for a Ramdisk or another memory resident program. Example 2 could just run on a system with 384 KB of memory. Example 2 Note: The above figures represent only coarse guidelines assuming Note: two typical examples. The exact requirements of a specific program are influenced by many different factors and may deviate from these examples quite considerably. Appendix A, SCL system details page 227 Appendix A, SCL system details page 227 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Tips & Tricks Tips & Tricks Entry of Characters not normally accessible via the keyboard Entry of Characters not normally accessible via the keyboard During the design of a format layout it is possible to redefine any keyboard key to any other character by using SFD's keyboard redefinition feature. Outside of the Layout Designer, such a feature does not exist. If you have to enter such a character outside the layout designer (for example to define a graphic character as a field delimiter), you can use a BIOS feature: Press the 'ALT' key, hold it down and key in the ASCII`value of the desired character in decimal, then release 'ALT'. This feature works on most 'compatible' machines and you can use it in many other programs as well. Blinking Fields Blinking Fields In case you use the 'Blink' field attribute set the SCL Constant 'Timer_Intervall' to a very low value. Fast blinking fields are much easier on the eyes than slow blinking ones. In general, for ergonomic reasons, try to avoid blinking fields at all whenever possible. Use of the 'Intensity' field attribute on Color systems Use of the 'Intensity' field attribute on Color systems If you use the 'Intensity' attribute together with 'Invert' to mark a field 'active' careful selection of the field background color can lead to interesting effects. If you assume for example 'Brown' as the background color this will lead to 'Yellow' foreground if the field becomes active. The 'Selected' Attribute in Menus The 'Selected' Attribute in Menus If a format only contains one group of 'Constant fields' like a typical menu, don't be concerned about any 'Selected' attributes since this format will instantly be terminated as soon as a field has been selected and for this reason it would never be visible anyway. Probably the nicest combination for such a field is to select 'Inverted' for active fields and no attributes at all for 'Selected'. Appendix A, tips and tricks page 228 Appendix A, tips and tricks page 228 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Preventing automatic termination of a format Preventing automatic termination of a format In some cases it may be desirable to prevent a format from being automatically terminated after the last field has been filled in. To achieve this, just add another field (A Constant) after the last field and ask the user via a message to press 'Return' to end the format (See Sample5). Highlighting text on screen formats Highlighting text on screen formats You can simply highlight text on a format by declaring this area of text as an 'output' field, then specify the field as being selected and choose the appropriate 'Selected' attributes according to the appearance you desire. If you want to switch the highlighting on and off while the format is being displayed, just use the 'W_Sel' construct. Special Fields Special Fields See Programming sample 5 for some suggestions and ideas. Storing strings in <Name>.ERR Storing strings in <Name>.ERR It is good practice to store text strings in the error message file instead of hardcoding them into the program itself. Any text stored in the error message file can be easily modified without recompiling the program which makes customization and/or nationalization much easier. Any strings stored in the error message file can be accessed using the function 'Sys_Msg'. Appendix A, tips and tricks page 229 Appendix A, tips and tricks page 229 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Using Field Input Messages for Help Screens Using Field Input Messages for Help Screens Especially on small formats it is not always possible to display field input messages. Using a 'User Interrupt Procedure', you can display these messages in an own format whenever for example 'F2' (Field Help) is pressed. This works as follows: Design a small format with just one 'output' field big enough to hold the field input message (70 characters long). Write a procedure similar to the following (assuming you named the above format 'Msg'). PROCEDURE Msg_Help; {Loads format 'Msg' and displays the Field} BEGIN; {Msg of the present field in it if F2 is pressed} IF User_Function_Key and Char_Code = Code_F2 THEN BEGIN; WITH Stack[S_Ptr].Field[Active_Field] DO BEGIN; IF (Field_Msg_Nr > 0) AND {a msg for this field exists} (Input_Msg_Nr = 0) AND {no field to display it} (Field_Help_Screen <= Spaces THEN {none defined} BEGIN{ Select_Format('Msg'); W_Cont(1,User_Msg(Field_Msg_Nr); {obtain the Msg} Display_Format(0,0); REPEAT Handle_Format UNTIL Format_Done; Char_Code:=Code_Noop; END; END; END; END; To use this feature declare the trigger key (here 'F2') as a user function key in all formats. Within your program, make a call to 'Msg_Help' in the format handling loop as follows: REPEAT Handle_Format; Msg_Help; {other optional interrupt handling statements} UNTIL Format_Done; This results in the following: Whenever the trigger key is pressed and a message is defined for the current field and if that format does not contain a message field and no help screen is defined for the current field then the format 'Msg' is called up displaying the message defined for the current field. Appendix A, tips and tricks page 230 Appendix A, tips and tricks page 230 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Using 'Goto_Field' Using 'Goto_Field' Sometimes it is desirable to skip one or more fields depending on a certain entry. For example, let's assume you have a format where you want to skip fields 5 and 6 if field 4 contains 'N'. This can be easily realized using 'Goto_Field' as the following example shows. REPEAT Handle_Format; IF end_of_field THEN BEGIN{ IF (Active_Field = 4) AND G_Cont(4) = 'N' THEN BEGIN; Goto_Field(7); Char_Code:=Code_Noop; {must do this because otherwise} END; {we would leave field 7 again} END; UNTIL Format_Done; Appendix A, tips and tricks page 231 Appendix A, tips and tricks page 231 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Appendix B Appendix B OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual This Page is intentionally left blank Appendix B, SCL procedures & functions page 233 Appendix B, SCL procedures & functions page 233 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Alphabethic List of all User accessible SCL Procedures & Functions Alphabethic List of all User accessible SCL Procedures & Functions Explanation of symbols used. Explanation of symbols used. + Full explanation in the SCL part of this manual. + Full explanation in the SCL part of this manual. * Usage possible. See text. * Usage possible. See text. / Usage possible but restricted. See text. / Usage possible but restricted. See text. F Function F Function P Procedure P Procedure + P Beep; + P Blank_Format; + F Capital(Wrkstr: String): String; + F Charstring(Whatchar:CHAR;Len:INTEGER):String; + P Check_Date(VAR Date_Str:String10;VAR Y,M,D:WORD); + P Check_Time(VAR Time_Str:String10;VAR H,M,S:WORD); + P Clear_Rx_Buffer; + P Close_Dc; + P Close_Formats; + F Cts:BOOLEAN; * P Cursor(Top,Bottom:byte); Sets cursor shape * P Cursor_off; Makes Cursor invisible + P C_Cont(Fieldnr:INTEGER); + F Date:String10; + F Date_String(Y,M,D:WORD):String10; * P DC(X,Y,Charcode:Byte); Writes Charcode at screen pos X,Y. * P Dc_Break; Sends a 'Break' onto the datacom line. + P Dc_Diagnose(On:BOOLEAN); + P Dc_Write(Code:Byte;VAR Ok:BOOLEAN); + P Disable_Port; + P Display_Format(Xoffset,Yoffset:INTEGER); + P DosExecute:String128); * P Draw_Char(Charcode:Byte); Writes Charcode at current pos on screen. + F Dsr:BOOLEAN; + P Enable_Port; + F Environment(Env_Name:String128):String128; + P Execute(Progstring:String128); + F Exist(Fn : String80):BOOLEAN; * P Fatal_Scl_Error(Errornr:INTEGER); Displays error msg and halts SCL. Dont use Errornr < 4, these are for internal use only. + P Finish_Format(Check:BOOLEAN); + F Format_Done:BOOLEAN; Appendix B, SCL procedures & functions page 234 Appendix B, SCL procedures & functions page 234 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual * F Format_Name:string80; Returns the name of the active format + P Frontstring(STR:String;VAR Head,Tail:String); * P Ftab(VAR Wrkstr:String;Fill_Char:CHAR; Just:Position;Len:INTEGER); Justifies Wrkstr in a field of length Len according to Just. All blanks are replaced by Fill_Char. See declaration of type Position. / F Get_Att(X,Y:INTEGER):Byte; Returns video attribute of position X,Y. X=1..80, Y=1..25. * P Get_Country; Updates Country dependant Info. If SCL_Country > 0 then Info is updated accordingly, otherwise according to CONFIG.SYS. + P Get_Dc_Status(VAR Status:INTEGER); / P Get_Next_Char(VAR Charnumber:INTEGER ; VAR Inputchar:CHAR); Waits until a key is pressed and returns Code and Image of the key. Code is SCL notation. Don't use together with background processing (you're stuck until a key is pressed). * P Get_Screen_Mode; Sets the variables Screen_Mode, Mono_Adapter and Color_True according to the current screen mode used. + P Goto_Field(Fn:INTEGER); + F G_Cont(Fn:INTEGER):String80; + F G_Sel(Fn:INTEGER):BOOLEAN; + P Handle_Format; + P Hp_Background_Task; FORWARD; * P Input_Error(Msgnr:INTEGER); Displays error msg in Err msg Field and beeps. + F Julian_Date(VAR Y,M,D:WORD):REAL; + F Justify_Center(STR:String;Len:INTEGER):String; + F Justify_Left(STR:String;Len:INTEGER):String; + F Justify_Right(STR:String;Len:INTEGER):String; / F Next_Char(VAR Esc:BOOLEAN):CHAR; Waits until a key is pressed and returns ASCII Code. If key generated a two byte code then 'Esc' is true. See 'Get_Next_Char' for restrictions. + P Normal_Date(Julian:REAL;VAR Y,M,D:WORD); + F Nr(St:String80):INTEGER; + P Open_Dc(VAR Result:INTEGER); / P Paint_Format_Frame(Color:Byte); Changes video attr. of first and last row and column of current format to color. S_Ptr must be valid ( > 0). + F Power(Mantissa,Exponent:REAL):REAL; + P Receive_Char(VAR Code:INTEGER;VAR Ok:BOOLEAN); + F Ri:BOOLEAN; + F Rnr(s:string80):real; + F Rst(r:Real;Decimals:integer):string; * F Rtime:REAL; Returns current time in hundreds of seconds since midnight. Appendix B, SCL procedures & functions page 235 Appendix B, SCL procedures & functions page 235 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual + P R_Cont(Fieldnr:INTEGER;VAR Contents:String80); + P R_Sel(Fieldnr:INTEGER; VAR Sel:BOOLEAN); + P Select_Format(Fname:String10); + P Select_Format_File(Filename:String10); + PSend_Buffer(VARTx_Buff;Buff_Start,Buff_Length,Bcc_add :INTEGER; + P Send_Char(Code:Byte;var Ok:BOOLEAN); + P Send_String(Data:String255;VAR Ok:BOOLEAN); / P Set_Att(X,Y:INTEGER;Color:Byte); Changes the video attribute at X,Y to color. X = 1..80, Y = 1..25. + P Set_Dc_Params; + P Set_Dtr(On:BOOLEAN); / P Set_Edit_Mode(Yes:BOOLEAN); Sets or resets edit mode. Make sure that Active_Field > 0. / P Set_Field_Color(Fieldnr:INTEGER;Color:Byte); Changes video attributes of current field to color. Fieldnr must be valid. / P Set_Mx(Value:INTEGER); Move Cursor to Column = Value. Conflicts with SCL likely. / P Set_My(Value:INTEGER); Move Cursor to Row = Value. Conflicts with SCL likely. + P Set_Rts(On:BOOLEAN); / P Set_Screen_Color(Color:Byte); Changes the complete screen to color (incl all fields). + F St(I:INTEGER):String80; + P Strip(VAR Wrkstr:String;VAR Len:INTEGER); + F Stripleft(Wrkstr: String): String; + F Stripright(Wrkstr: String): String; + F Sys_Msg(Nr:INTEGER):String80; + F Time(Seconds:BOOLEAN):String10; + F Time_String(H,M,S:WORD):String10; + F Tx_Ok:BOOLEAN; + F Weekday(Y,M,D:WORD):INTEGER; + P W_Cont(Fieldnr:INTEGER;Cont:String80); / P W_Crt(Fieldnr:INTEGER;Msg:String80); Writes Msg to the specified field. Does not change/Update Format content (Screen only). S_Ptr must be valid (>0). + P W_Sel(Fieldnr:INTEGER;Sel:BOOLEAN); + F X_Max:INTEGER; + F Y_Max:INTEGER; Appendix B, SCL procedures & functions page 236 Appendix B, SCL procedures & functions page 236 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Datacom Control Characters Datacom Control Characters CONST Nul = $0; Soh = $1; Stx = $2; Etx = $3; Eot = $4; Enq = $5; Ack = $6; Bel = $7; Con = $7; Bs = $8; Ht = $9; Lf = $a; Vt = $b; Ff = $c; Cr = $d; S0 = $e; S1 = $f; Dle = $10; Dc1 = $11; Dc2 = $12; Dc3 = $13; Dc4 = $14; Nak = $15; Syn = $16; Etb = $17; Can = $18; Em = $19; Sub = $1a; Esc = $1b; Fs = $1c; Gs = $1d; Rs = $1e; Us = $1f; Pol = $70; Sel = $71; Fsl = $73; Bsl = $74; Del = $7f; Appendix B, SCL procedures & functions page 237 Appendix B, SCL procedures & functions page 237 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Field Attributes and Colors Field Attributes and Colors ___________________________ Possible Field Attributes: Possible Field Attributes: -------- Monochrome ---------- Normal Active Selected Active (Color)----- ----------------------------------------------------------- Inverted N Y Y Y Intensity Y Y Y Y Underlined N Y Y N Marked N Y 1) Y N Blink N Y N Y 1) The marks blink if used as an attribute for 'Active'. Note: Multiple choices of the above attributes are possible. Refer Note: to the SFD part of the manual for restrictions applying to certain combinations of attributes. 'Normal' and 'Selected' on color systems are specified by any valid Foreground/Background color combination according to the table below. Colors. (Systems with color graphics adapter). Colors. (Systems with color graphics adapter). Background Foreground --------------------------------------- Black Y Y Blue Y Y Green Y Y Cyan Y Y Red Y Y Magenta Y Y Brown Y Y Light grey Y Y Dark Grey N Y Light Blue N Y Light Green N Y Light Cyan N Y Light Red N Y Light Magenta N Y Yellow N Y White N Y Appendix B, SCL procedures & functions page 238 Appendix B, SCL procedures & functions page 238 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Functions in SCL Programs Functions in SCL Programs _________________________ Right : 1. In Travel Mode : Next Field. Travel Mode 2. In Entry Mode : Next Character. Entry Mode Left : 1. In Travel Mode : Previous Field. Travel Mode 2. In Entry Mode : Previous Character. Entry Mode Down : First field on next line. Up : Last field on previous line. Home : First field in line. End : Last field in line. PgDn : Last field on format. PgUp : First field on format. Tab : Next field. ShiftTab : Previous field. Backspace : Delete character left of cursor. Insert : Insert a space at the cursor position. Delete : Delete character under cursor. Return : 1. Entry mode. 2. Finish field and advance to next field (if already in the last field, finish the format). 3. Toggle Selected Status of a Constant. Selected Escape : Finish Format. F1 : Format related Help information. F2 : Field related Help information. F3 : UNDO. Restores field to previous content. F10 : Abort current activity (not valid with every format). Appendix B, SCL procedures & functions page 239 Appendix B, SCL procedures & functions page 239 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Standard SCL Error Messages Standard SCL Error Messages ___________________________ <1> Format File not found <2> Not enough Memory to run <3> This program requires 80 column screen <4> Format does not fit at specified location <5> Format not found <6> Insufficient Mem in Heap for screen <7> Runtime or I/O error while SCL was running <8> Format file not sorted or integrity error <9> Attempt to read field while format read pointer is zero <10> Attempt to read from invalid fieldnumber <11> Break key pressed <12> Attempt to write to field while format write pointer is zero <13> Attempt to write to invalid field number <14> Invalid path specified <15> Invalid Key Pressed <16> Warning: End of Field <17> Format has only one Field <18> Input mandatory <19> Numeric Data expected <20> Value entered too small <21> Value entered too big <22> <23> <24> <25> <26> <27> <28> <29> <30> <31> <32> <33> <34> <35> <36> Integer number expected <37> Helpfile not available <38> This Helpfunction not available <39> Autohelp-Format not found <40> Appendix B, SCL procedures & functions page 240 Appendix B, SCL procedures & functions page 240 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual The Shareware Idea The Shareware Idea Shareware (sometimes called User supported Software or freeware) attempts to provide useful programs to the PC community at low cost by reducing the dependence on conventional marketing channels. Several software developers have proven that the concept works, to the mutual benefit of the independent program authors and the PC community itself. The user benefits by the availability of low cost software which he can evaluate on his own system before making the decision to purchase it. The author benefits by being able to enter the software market without extensive monetary risks. The user community determines which products succeed based on their true utility, rather than on their marketing achievements. Appendix B, OASIS products page 241 Appendix B, OASIS products page 241 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual OASIS Products & Licencing Terms OASIS Products & Licencing Terms The following products will be available from EUREKA SOFTWARE ASSOCIATES: - OASIS Demo package - OASIS Evaluation software - OASIS OASIS Demo package OASIS Demo package __________________ Description Description This package as its name indicates is only to be used for demonstration purposes. It is ment to give you a taste of what you can achieve with OASIS. Each demo application comes with the source code and the associated documentation commenting each procedure. This package does not require you to register, feel free to copy and distribute this package and use some of its handy utilities. Distribution Distribution - Download - Mail order Pricing (No registration required) Pricing - Download no charge - Mail order $10 includes disk & hard copy Appendix B, OASIS products page 242 Appendix B, OASIS products page 242 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual OASIS Evaluation (This package) OASIS Evaluation ________________ Description Description This package is the evaluation version of OASIS. It offers almost all OASIS features and formats (screens) created with the evaluation version are entirely compatible with full blown version of OASIS. The limitation of this version resides in the number of formats (screens) you can handle in any single file, the limit is set to 20 for OASIS Evaluation. This mean you can still create an application that requires up to 20 screens, for more complexe applications with more screens you need the full version of OASIS. Distribution Distribution - Download - Mail order Licencing Terms Licencing Terms OASIS Evaluation is NOT public domain software, it is a copyrighted product distributed by EUREKA SOFTWARE ASSOCIATES. You are hereby granted a limited license to use OASIS, and to copy it and further distribute it, under the following conditions: 1) No fee other than the cost of media and copying (max $10 per copy) may be charged for such copying and distribution, otherwise permission of EUREKA SOFTWARE ASSOCIATES is required. 2) OASIS Evaluation may ONLY be distributed in its original state, complete and without any modifications or changes to the program itself or to any of its data files. 3) Use without registration must be limited to a reasonable time (no more than 14 days) and for test and evaluation purposes only, after which it must be registered in accordance with the following terms. Appendix B, OASIS products page 243 Appendix B, OASIS products page 243 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Commercial use: ______________ If OASIS Evaluation Software is used in a commercial & institutional environment users must register under the 'Commercial Users Licence Agreement' scheme. Any use of OASIS Evaluation beyond the trial period is a copyright violation. Conditions: Within the terms of this agreement, a corporation, company, institution, organization, or individual can use OASIS Evaluation to produce programs for commercial purposes subject to the following conditions: 1. This license applies to the OASIS Evaluation software as described in this manual and its documentation. 2. You must treat this software just like a book ONLY ONE CPU PER LICENSE can use the software at the same time in the original or modified forms. However, you are authorized to make archival copies for safekeeping. 3. You may produce any number of executable code programs for profit for world-wide distribution with this software without royalties to the author. 4. The license applies to the original copy of this software as well as to updated versions which may become available. There is no further charge for using the updated versions. The author is neither obligated to provide updated versions nor notices of error corrections. The author is not obligated to provide any services of any kind to support OASIS Evaluation . 6. The user agrees to conscientiously respect the copyright to the author of the code and not to illegally, unethically, or neglectfully exploit the services provided by the author. 7. This code is provided "as is" without warranty of any kind, either expressed or implied, included but not limited to the implied warranty of merchantability and fitness for a specific purpose. The entire risk as to the quality and performance of the coding is with you. Should the code prove defective, you assume the entire cost of all necessary servicing, repair or correction. 8. In no event will the author be liable to you for any damages, including any lost profits, lost savings or other incidental or consequential damages arising out of the use or inability to use this code. 9. The User acknowledges having read this agreement and the License Statement, understands them, and agrees to be bound by their terms and conditions. Appendix B, OASIS products page 244 Appendix B, OASIS products page 244 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Private (non-profit) use: ________________________ If OASIS Evaluation is used privately only and not for profit making purposes, please register under the private user licence agreement scheme. The applicable terms are, apart from point 3, identical to the ones listed above. Pricing Pricing Registration Registration $40 does not include disk or manual Private Licence Private Licence includes registration, distribution disks $60 & reference manual on disk includes registration, distribution disks $80 & with hard copy manual Commercial Users Licence Commercial Users Licence includes registration, distibution disks $120 & hard copy manual. Appendix B, OASIS products page 245 Appendix B, OASIS products page 245 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual OASIS OASIS _____ Description Description Identical to OASIS Evaluation but no limit to the number of format per file. Distribution Distribution - Mail order Note: Application available, Documentation draft version approx. 250 pages. Licensing terms Licensing terms - Same as OASIS Evaluation Commercial use. Pricing Pricing - includes registration, distibution disks $199 & hard copy manual. Appendix B, OASIS products page 246 Appendix B, OASIS products page 246 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual ------------------------ | Invoice & Order Form | Invoice & Order Form ------------------------ ================================================================= " O R D E R F O R M " O R D E R F O R M "===============================================================" " Date: __ / __ / __ PO#: ______________ " "---------------------------------------------------------------" " Qty Description $/unit " "---------------------------------------------------------------" " | | | " " __ |OASIS Demo package mail order * | $10.00 |___.__ " " | | | " " __ |OASIS Evaluation Registration | $40.00 |___.__ " " |(does not include disk) | | " " | | | " " __ |OASIS Evaluation Private Licence * | $60.00 |___.__ " " |(registration, disks, manual on disk) | | " " | | | " " __ |OASIS Evaluation Private Licence ** | $80.00 |___.__ " " |(registration, disks and manual) | | " " | | | " " __ |OASIS Evaluation Commercial User Licence|$120.00 |___.__ " " |(registration, disks and manual) ** | | " " | | | " " __ |OASIS Commercial User Licence ** |$199.00 |___.__ " " |(registration, disks and manual) | | " " | | | " "===============================================================" " Michigan residents add 4% sales tax Subtotal: $____.__ " " Shipping per order Shipping: $____.__ " " * US $3 first copy, $1 other copies Tax: $____.__ " " ** US $3 first copy, $2 other copies Total: $____.__ " Total "---------------------------------------------------------------" " Method of Payment: ( ) Check ( ) Money Order " " " " Make check payable to: EUREKA SOFTWARE ASSOCIATES " EUREKA SOFTWARE ASSOCIATES " 2344 Yorkshire " " Ann Arbor, MI 48104 " " USA " " " " For orders outside the U.S. please send check drawn on U.S. " " bank in U.S. dollars, or international money order in U.S. " " dollars. " "===============================================================" " Name: ________________________________________________ " " Address: ________________________________________________ " " ________________________________________________ " " City: ______________________ State: __ Zip: _____ " " " ================================================================= Appendix B, OASIS products page 247 Appendix B, OASIS products page 247 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual ------------------------ | Invoice & Order Form | Invoice & Order Form ------------------------ ================================================================= " I N V O I C E " I N V O I C E "===============================================================" " Date: __ / __ / __ PO#: ______________ " "---------------------------------------------------------------" " Qty Description $/unit " "---------------------------------------------------------------" " | | | " " __ |OASIS Demo package mail order | $10.00 |___.__ " " | | | " " __ |OASIS Evaluation Registration | $40.00 |___.__ " " |(does not include disk) | | " " | | | " " __ |OASIS Evaluation Private Licence | $60.00 |___.__ " " |(registration, disks & manual on disk) | | " " | | | " " __ |OASIS Evaluation Private Licence | $80.00 |___.__ " " |(registration, disks and manual) | | " " | | | " " __ |OASIS Evaluation Commercial User Licence|$120.00 |___.__ " " |(registration, disks and manual) | | " " | | | " " __ |OASIS Commercial User Licence |$199.00 |___.__ " " |(registration, disks and manual) | | " " | | | " "===============================================================" " Remit to: Subtotal: $____.__ " " EUREKA SOFTWARE ASSOCIATES Shipping: $____.__ " " 2344 Yorkshire Tax: $____.__ " " Ann Arbor, MI 48104 USA Total: $____.__ " Total "===============================================================" " SOLD TO: " " " " Name: ________________________________________________ " " Address: ________________________________________________ " " ________________________________________________ " " City: ______________________ State: __ Zip: _____ " " Country: ______________________ " " " "---------------------------------------------------------------" " SHIP TO: " " " " Name: ________________________________________________ " " Address: ________________________________________________ " " ________________________________________________ " " City: ______________________ State: __ Zip: _____ " " Country: ______________________ " " " ================================================================= Appendix B, OASIS products page 248 Appendix B, OASIS products page 248 OASIS Evaluation Reference Manual OASIS Evaluation Reference Manual Appendix B, OASIS products page 249 Appendix B, OASIS products page 249